Copyright: Copyright 1995-1996, Catalyst Development Corp.


Contents
Catalyst SocketTools Custom Controls
Copyright Information        License Agreement       Technical Support

	Domain Name Service		Remote Command Execution
	File Transfer Protocol		Simple Mail Transfer Protocol
	Image Viewer		Telnet Network Terminal
	Internet Control Message Protocol		Terminal Emulator
	Network News Protocol		Web Browser
	Post Office Protocol		Windows Sockets
	Remote Access Service


Copyright
Copyright © 1995-1996 Catalyst Development Corporation. All rights reserved.

SocketWrench and SocketTools are trademarks of Catalyst Development Corporation. Microsoft, Windows, Windows NT and Visual Basic are trademarks or registered trademarks of Microsoft Corporation.

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Catalyst Development Corporation.

The software described in this document is furnished under a license agreement. The software may be used only in accordance with the terms of the agreement. It is against the law to copy the software except as specifically allowed in the license agreement. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the purchaser's personal use, without the express written permission of Catalyst Development Corporation.


License Agreement
SocketTools License Agreement

GRANT OF LICENSE.  CATALYST (Catalyst Development Corporation) grants to you, the end user, the right to use one copy of the Catalyst SocketTools developer toolkit. (Known as the "SOFTWARE".) The SOFTWARE may be on a single workstation or computer. You may not network the SOFTWARE or otherwise use it on more than one computer or workstation at the same time. Contact CATALYST for more information regarding our multi-developer site licenses.

DISTRIBUTION.  The purchaser does retain the right to sell or distribute an unlimited number of "end-user programs that contain or otherwise access CATALYST component routines (including DLLs, VBXs, and OCXs), so long as the primary purpose of the included routines is to augment the software being sold or distributed. The purchaser may not distribute programs that utilize CATALYST routines if those programs are part of a programming toolkit or other application which will be redistributed or resold by purchaser's customers. The SOFTWARE is free of royalty and/or subsequent licensing fees in accordance with the above stated conditions.

COPYRIGHT.  The SOFTWARE is owned by CATALYST and is protected by copyright laws and international treaty provisions. Therefore you must treat the SOFTWARE like any other copyrighted material (e.g. a book or musical recording) EXCEPT that you may either (a) make one copy of the SOFTWARE solely for backup or archival purposes or (b) transfer the SOFTWARE to a single hard disk provided you keep the original solely for backup or archival purposes.

OTHER RESTRICTIONS.  You may not RENT or LEASE the software, but you may transfer the SOFTWARE and accompanying written materials on a permanent basis provided that you retain no copies and the recipient agrees to the terms of this Agreement. You may not reverse engineer, decompile or disassemble the SOFTWARE.

LIMITED WARRANTY and CUSTOMER REMEDIES.  If within 90 days of your purchase of this software product,  you become dissatisfied with the SOFTWARE for any reason, contact us and you will be given a return material authorization (RMA) number and you may return the software to CATALYST (or your dealer, if you did not purchase it directly from CATALYST) for a refund of your purchase price, CATALYST will not accept returns of opened software without an RMA number.

NO OTHER WARRANTIES.  CATALYST disclaims all other warranties, either express or implied, including but not limited to implied warranty of merchantability and fitness for a particular purpose, with respect to the SOFTWARE, the accompanying written materials, and any accompanying hardware.

NO LIABILITY FOR CONSEQUENTIAL DAMAGES.  In no event shall CATALYST or its suppliers be liable for any damages whatsoever (including, with limitation, damages for loss of business profits, business interruption, or other pecuniary loss) arising out of the use or inability of this CATALYST product, even if CATALYST has been advised of such damages.

Apart form the foregoing limited warranty, the software programs are provided "AS-IS", without warranty of any kind, either expressed or implied. The entire risk as to the performance of the programs is with the purchaser. CATALYST does not warrant that the operation of the programs will be uninterrupted or error-free. CATALYST assumes no responsibility or liability of any kind for errors in the programs or documentation, of/for the consequences of any such errors. This agreement is governed by the laws of the state of California.


Technical Support

If you have a question about SocketTools, first look in the product documentation or consult online help.  You can also find additional information about updates and other technical information in the README file that was included with your SocketTools diskettes. If you are unable to find the information that you are looking for, contact Catalyst Technical Support.

Free Technical Support

Unlimited technical support through on-line services or electronic mail is available 24-hours a day, seven days a week. This is the preferred way to contact us with technical problems or questions. You can reach us through the following services:

Internet:	support@catalyst.com
World Wide Web:	http://www.catalyst.com/
CompuServe:	72202,1427

Standard Technical Support

Unlimited technical support related to setup and installation is available via toll call between 8:30 AM and 6:00 PM Pacific time, Monday through Friday, excluding holidays. For other support issues, free support is offered for thirty (30) days after your first call. Calls made after the thirty day time period are charged at $50US per incident. There is never any charge for reporting a defect in the product. Catalyst Technical Support can be reached at the following telephone numbers:

Voice:	(818) 997-0110
Fax:	(818) 997-0550

When You Contact Us

When you call, you should be at your computer and have the appropriate product documentation at hand. Please be prepared to give the following information:

•  Product serial number
•  The type of hardware that you are using and version of operating system
•  The vendor and version of the TCP/IP software installed on the system
•  Product component type and development environment
•  The exact wording of any messages that were displayed on the screen
•  A description of the sequence of events that leads to the problem
•  A description of how you attempted to resolve the problem

If you are contacting us through an electronic service (the Internet, CompuSeve) or by FAX, please include the above information in your message. This allows us to provide the most efficient, timely service possible.


Glossary
Anchor
Fragment Identifier
Universal Resource Locator


Address - Internet

The term address in this context refers to a 32-bit number which uniquely identifies a remote host on a network. An internet address is expressed in dot notation, which consists of each of the four bytes in the address seperated by periods.

Internet addresses are commonly mapped to logical names, either through a local database (called a hosts file) or over the network through a domain name server.


Address - Socket

The term address in this context refers to a combination of an internet address, a service port and address family. For those applications that do not care to specify the internet address, the constant INADDR_ANY can be used.


Anchor
An anchor references a point in the current document which may be the target of a link. This is most commonly used in large documents which have several sections. By embedding an anchor in the document, the client can quickly "jump" to the text marked by the anchor. An anchor is referenced by using a fragment identifier in the URL.


Cache file
A temporary file used to store the contents of a file from a remote system. Use of a cache file improves performance because the data only needs to be transferred from the remote system once, even if it is referenced many times.


External viewer
An external viewer is a program capable of viewing a specific type of file outside of the browser control. An external viewer may be used to view graphics images, video clips, audio clips, etc. When an external viewer is required, the control's Execute event will be triggered.


Fragment identifier
A fragment identifier is anything that follows a hash mark in the URL, and is used to reference an anchor in the target document. For example, in the hypothetical URL http://www.company.com/index.html#finance, the string "finance" is the fragment identifier. Once the document is loaded, the current position in the document is changed to the location of the text marked by that anchor.


HTML
The Hypertext Markup Language is a simple markup language used to create platform-indenpendant hypertext documents. The document itself is plain text, and uses markup tags to specify characteristics of the text. It is the responsibility of the document viewer to recognize and process these tags.


HTTP
The Hypertext Transfer Protocol is an application protocol that is used by clients to request resources from remote systems.


In-line graphics
An in-line graphics image is referenced in the document through the <IMG> tag and is displayed along with the text of the document. The control is capable of displaying BMP, GIF, JPEG, PCX and XBM images in the document. Other image types require the use of an external viewer.


Method
A method identifies which application protocol should be used to retrieve the requested resource. The browser control recognizes two methods, http and file. The http method specifies that the resource should be retrieved from an HTTP server, while the file method specifies that the resource is local to the client system.


Relative URL
A relative URL is one that does not specify the method or hostname and the path does not begin with a slash. In other words, the resource is relative to the server and path where the current document was loaded. For example, consider:

http://www.somewhere.org/doc/info.html

If the file data.html is referenced, this is considered to be relative to the current document, and would be resolved as:

http://www.somewhere.org/doc/data.html

The advantage of relative URL's is that they allow the files referenced by a document to be moved with the document, without having to change it's contents. Note that a document may change the base URL used for locating relative links by specifying the <BASE> tag.


Request header
When a resource is requested from a remote server, a block of information is sent to the server describing the request. Typically, the request header includes information on the location of the resource, what types of resources the client is willing to accept, authentication information, etc.


Resource
A resource is general term used to refer to a file that contains data which is used by the document viewer, or another application in conjunction with the viewer. Most commonly, resources refer to graphic images, sounds, etc. that are referenced by the document.


Universal resource locator
A universal resource locator (URL) is a string which specifies how a client application is to retrieve a document, data file or other resource over the network. The URL is comprised of several parts, and has the format of:

method://hostname:port/path/file#anchor

The method refers to the protocol that should be used to retrieve the resource. The Web client control uses either the http method (to retrieve files over the network), or the file method (to retrieve files local to the client system).

The hostname refers to the host name or IP address of the system that the resource is located on. If the resource is local, this part of the URL should be omitted.

The port refers to the port number of the server on the remote host. If the port is not specified, the default port number for the specific method is used. For the http method, the port number is 80.

The path refers to what directory the resource is stored in. Forward slashes should be used to seperate subdirectories in the path, even if a different convention is used on the remote host operating system (such as backslashes for Windows NT or brackets for VMS).

The file refers to the filename of the resource to be retrieved. Note that the name may be case-sensitive on some operating systems, such as UNIX.

The anchor is an optional fragment identifier which refers to a specific section of an HTML document.


Common Properties


Action Property
Action Properties

Domain Name Service
File Transfer Protocol
Internet Control Message Protocol (Ping)
Network News Protocol
Post Office Protocol
Remote Access Service
Remote Command
Simple Mail Transfer Protocol
Telnet
Terminal Emulation
Windows Sockets
World Wide Web


Blocking Property

Description

Sets or returns the blocking state of the control.

Visual Basic

[form.]control.Blocking [= { True | False }]

Remarks

Setting the Blocking property determines if control actions complete synchronously or asynchronously. If set to True, then each control action (such as sending or receiving data) will return when the operation has completed or timed-out. If set to False, control actions will return immediately. If the operation would result in the control blocking (such as attempting to receive data when none has been written), an error is generated. Control events such as Disconnect, Read and Write are only fired if the socket is non-blocking.

Data Type

Integer (Boolean)

See Also

IsBlocked Property


Connected Property

Description

Return if the control is connected to a remote host.

Visual Basic

[form.]control.Connected

Remarks

The Connected read-only property is set to a value of True if the control is connected with a remote server, otherwise the property has a value of False.

Data Type

Integer (Boolean)


Handle Property

Description

Returns the handle for the client control.

Visual Basic

[form.]control.Handle

Remarks

The Handle read-only property returns the handle to the client control. Unlike the hWnd property, which returns a handle to the control's window, the client handle is an index into an internal table of active connections established by the control. A value of -1 indicates that the control has not established a connection with a remote server.

Data Type

Integer

See Also

Socket Property


HostAddress Property

Description

Set or return the IP address of the remote host.

Visual Basic

[form.]control.HostAddress [= addr$]

Remarks

The HostAddress property can be used to set the IP address for a remote system that you wish to communicate with. If the address is valid and matches an entry in the host table, the HostName property will be changed to match the address.

Data Type

String

See Also

HostName Property, LocalAddress Property


HostName Property

Description

Set or return the name of the remote host.

Visual Basic

[form.]control.HostName [= hostname$]

Remarks

The HostName property should be set to the name of the remote system that you wish to communicate with. If the name is found in the host table, the HostAddress property is updated to reflect the IP address of the host.

Note  It is legal to assign an IP address to this property, but it is not legal to assign a host name to the HostAddress property.

Data Type

String

See Also

HostAddress Property, LocalName Property


IsBlocked Property

Description

Return if the control is blocked performing an operation.

Visual Basic

[form.]control.IsBlocked

Remarks

The IsBlocked property returns True if the specified control is blocked performing an operation. Because the Windows Sockets API only permits one blocking operation per thread of execution, this property should be checked before starting any blocking operation.

Note  This property will return True if there is any blocking operation being performed by the application, regardless if the specified control is responsible for the blocking operation or not.

Data Type

Integer (Boolean)

See Also

Action Property, Blocking Property


IsClosed Property

Description

Return if the connection has been closed by the remote host.

Visual Basic

[form.]control.IsClosed

Remarks

The IsClosed property returns True if the socket connection has been closed by the remote host.

Note  It is possible to continue to receive data on a closed socket due to buffering.

Data Type

Integer (Boolean)

See Also

IsReadable Property, IsWritable Property


IsReadable Property

Description

Return if data can be read from the socket without blocking.

Visual Basic

[form.]control.IsReadable

Remarks

The IsReadable property returns True if data can be read from the socket without blocking. For non-blocking sockets, this property can be checked before the application attempts to read the socket, preventing an error.

Data Type

Integer (Boolean)

See Also

IsClosed Property, IsWritable Property, Read Event


IsWritable Property

Description

Return if data can be written to the socket without blocking.

Visual Basic

[form.]control.IsWritable

Remarks

The IsWritable property returns True if data can be written to the socket without blocking. For non-blocking sockets, this property can be checked before the application attempts to write to the socket, preventing an error.

Data Type

Integer (Boolean)

See Also

IsClosed Property, IsReadable Property, Write Event


LastError Property

Description

Set or return the last error that occurred on the control.

Visual Basic

[form.]control.LastError [= errval%]

Remarks

The LastError property can be read to determine the last error that occurred for this control. If a value is assigned to this property, it must either be zero (to clear the error) or a valid  error code for the control.

Data Type

Integer

See Also

SocketError Property, LastError Event


LocalAddress Property

Description

Return the IP address of the local host.

Visual Basic

[form.]control.LocalAddress

Remarks

The LocalAddress read-only property returns the local host’s IP address in dot notation (four numbers separated by periods).

Data Type

String

See Also

HostAddress Property, LocalName Property


LocalName Property

Description

Return the name of the local host.

Visual Basic

[form.]control.LocalName

Remarks

The LocalName read-only property returns the name of the local host. The name that is returned depends on the configuration of the TCP/IP software.

Data Type

String

See Also

HostName Property, LocalAddress Property


Password Property

Description

The password for the current user.

Visual Basic

[form.]control.Password [= password $]

Remarks

The Password property specifies the password used to authenticate the user. If a password is not required by the server, this property is ignored.

Data Type

String

See Also

UserName Property


RecvData Property

Description

Return data read from the remote server.

Visual Basic

[form.]control.RecvData

Remarks

The RecvData property returns data that has been read from the remote server, up to the number of bytes specified by the RecvLen property. If no data is available to be read, an error will be generated if the control is non-blocking. If the control is blocking, the program will stop until data is written by the server, or the connection is closed.

Note that there may be fewer bytes returned than specified by the RecvLen property.

Data Type

String

See Also

RecvLen Property, RecvNext Property, SendData Property, Read Event


RecvLen Property

Description

Set the maximum number of bytes to read, or return the number of bytes read.

Visual Basic

[form.]control.RecvLen [= maxlen%]

Remarks

If set to a value, RecvLen specifies the maximum number of bytes that may be returned by the RecvData property. After the data has been read, RecvLen contains the actual number of bytes that have been read.

Note  It is common for the number of bytes to be read from the server to be fewer than that which was specified. The application should never make any assumptions about the number of bytes received. If an error occurs, or the connection is closed, this property will have a value of zero.

Data Type

Integer

See Also

RecvData Property, RecvNext Property, Read Event


RecvNext Property

Description

Return the number of bytes available to be read from the server.

Visual Basic

[form.]control.RecvNext

Remarks

The RecvNext read-only property returns the number of bytes that are available to be read from the server. If the connection is buffered, which is typically the case, it is possible that this property will return a non-zero value after the socket has been closed.

Data Type

Integer

See Also

RecvData Property, RecvLen Property, Read Event


RemotePort Property

Description

Set or return the port number for a remote connection.

Visual Basic

[form.]control.RemotePort [= portno%]

Remarks

The RemotePort property is used to set the port number that the control will use to establish a connection with the remote server. If the port number specifies a well-known port, the RemoteService property will be updated with that name.

Data Type

Integer

See Also

RemoteService Property


RemoteService Property

Description

Set or return the name of a well-known remote port.

Visual Basic

[form.]control.RemoteService [= servicename$]

Remarks

The RemoteService property is used to set the port that the control will use to establish a connection with a remote server. If the service name does not exist, an error is generated. The RemotePort property is updated to reflect the service’s port number.

Data Type

String

See Also

RemotePort Property


ResultCode Property

Description

Return the result code of the previous action.

Visual Basic

[form.]control.ResultCode

Remarks

The ResultCode read-only property returns the result code of the last action performed by the client. This property should be checked after the Action property is set to determine if the operation was successful. Result codes are either boolean (in which a zero value indicates an error and a non-zero value indicates sucess), or are three-digit numeric values returned by the remote server. If the result codes fall into the later catagory, they may be broken down into the following ranges:

Value	Description
100-199	Positive preliminary result. This indicates that the requested action is being initiated, and the client should expect another reply from the server before proceeding.
200-299	Positive completion result. This indicates that the server has successfully completed the requested action.
300-399	Positive intermediate result. This indicates that the requested action cannot complete until additional information is provided to the server.
400-499	Transient negative completion result. This indicates that the requested action did not take place, but the error condition is temporary and may be attempted again.
500-599	Permanent negative completion result. This indicates that the requested action did not take place.
Currently, of those servers that return result codes, only the POP3 server returns a boolean result code. All others return numeric result codes.

Data Type

Integer

See Also

ResultString Property


ResultString Property

Description

Return a string describing the results of the previous action.

Visual Basic

[form.]control.ResultString

Remarks

The ResultString read-only property returns the result string from the last action taken by the client. This string is generated by the remote server, and typically is used to describe the result code. For example, if an error is indicated by the result code, the result string may describe the condition that caused the error.

Data Type

String

See Also

ResultCode Property


SendData Property

Description

Write data to the remote server.

Visual Basic

[form.]control.SendData = data$

Remarks

By assigning a value to the SendData property, the data in the string is written to the remote server. If the connection is buffered, as is typically the case, the data is copied to the send buffer and control immediately returns to the program. If the control is non-blocking and is out of buffer space, an error will be generated. If the control is blocking, the application will wait until the data can be sent.

The maximum number of bytes written on the socket is determined by the SendLen property. It is possible that fewer than the number of bytes specified will be written to the socket. After the data has been written, the SendLen property will be changed to reflect the number of bytes actually written to the socket. If the socket is non-blocking and the send fails because it could not write all of the data to the server, the Write event will be fired when the server can be written to again.

Data Type

String

See Also

SendLen Property, Timeout Property, Write Event


SendLen Property

Description

Set or return the maximum number of bytes to write to the server.

Visual Basic

[form.]control.SendLen [= datalen%]

Remarks

If set to a value, the SendLen property specifies the maximum number of bytes that may be written to the server. If this value is greater than the length of the string being sent, the value is ignored and all of the characters are sent.

After data has been written to the server, the SendLen property is updated to reflect the actual number of bytes written.

Data Type

Integer

See Also

SendData Property, Write Event


Socket Property

Description

Returns the descriptor for the current socket.

Visual Basic

[form.]control.Socket

Remarks

The Socket read-only property returns the descriptor of the socket being used by the control. If the control is not connected to a remote host, a value of -1 is returned. This property can be used in conjunction with direct calls to the Windows Sockets API.

Data Type

Integer

See Also

Handle Property


Timeout Property

Description

Set or return the amount of time until a blocking operation fails.

Visual Basic

[form.]control.Timeout [= secs ]

Remarks

Setting the Timeout property specifies the number of seconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely.

Data Type

Integer

See Also

RecvData Property, SendData Property


UserName Property

Description

Set or return the current user name.

Visual Basic

[form.]control.UserName [= name$]

Remarks

The UserName property specifies the user that is logging in to the remote server, and is required for authentication purposes.

Data Type

String

See Also

Password Property


Vendor Property

Description

Returns the name of the TCP/IP vendor.

Visual Basic

[form.]control.Vendor

Remarks

The Vendor read-only property returns a string that contains the name of the vendor that has supplied the Windows Sockets library that is being used.

Data Type

String

See Also

Version Property


Version Property

Description

Returns the version of the Windows controls library.

Visual Basic

[form.]control.Version

Remarks

The Version read-only property returns a string that specifies the version of the Windows Sockets library that is being used.

Note At least version 1.1 is required for use with this control.

Data Type

String

See Also

Vendor Property


AutoResolve Property

Description

Determines if host names and addresses are automatically resolved.

Visual Basic

[form.]control.AutoResolve [= { True | False }]

Remarks

Setting the AutoResolve property determines if the control automatically resolves host names and addresses specified by the HostName and HostAddress properties. If set to True, setting the HostName property will cause the control to automatically determine the corresponding IP address and set the HostAddress property accordingly. Likewise, setting the HostAddress property will cause the control to determine the host name and set the HostName property. Setting the property to False prevents the control from resolving host names until a connection attempt is made.

Note When using the domain name service (DNS), setting the HostName or HostAddress property may cause the application to block, sometimes for several seconds, until the name or address is resolved. To prevent this behavior, set AutoResolve to False.

Data Type

Integer (Boolean)

See Also

HostAddress Property, HostName Property


Library Property

Description

Sets or returns the file name of the Windows Sockets library

Visual Basic

[form.]Socket.Library [= libfile$]

Remarks

The Library property returns the full pathname of the Windows Sockets library loaded by the control. Setting the property to the file name of an appropriate DLL causes that library to be loaded. By default, a file named WINSOCK.DLL is loaded for 16-bit versions of the control, and WSOCK32.DLL for 32-bit versions.

Note This should be the first property set by the control when it is loaded. Attempting to set this property after a library has already been loaded will generate an error.

Data Type

String


SocketError Property

Description

Set or return the last socket error that occurred on the control.

Visual Basic

[form.]control.SocketError

Remarks

This read-only property returns the last socket error that was generated by the application. The error codes are the same as those returned by the Windows Sockets control.

Note  If there are multiple networking controls being used by the application, an error in any one of the controls will change this value. For that reason, it is important to read the property value immediately after an error is reported by the control.

Data Type

Integer

See Also

LastError Property, LastError Event


State Property
State Properties

File Transfer Protocol
Network News Protocol
Post Office Protocol
Remote Access Service
Remote Command
Simple Mail Transfer Protocol
Telnet
Windows Sockets
World Wide Web


Common Methods
Methods


Cancel Method

Description

Cancels the current operation.

Visual Basic

[form.]control.Cancel

Remarks

The Cancel method cancels a blocking operation and attempts to reset the control's state.

Return Value

None

See Also

Reset Method


Connect Method

Description

Establish a connection with a remote server

Visual Basic

[form.]control.Connect

Remarks

This method establishes a network connection with a remote server. The HostAddress or HostName properties, as well as the RemotePort or RemoteService properties, must be set before attempting the connection.

Return Value

A value of zero is returned if the connection was successful. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, HostAddress Property, HostName Property, RemotePort Property, RemoteService Property, Disconnect Method


Disconnect Method

Description

Terminate the connection with a remote server

Visual Basic

[form.]control.Disconnect

Remarks

This method terminates a network connection with a remote server.

Return Value

A value of zero is returned if the connection was terminated successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Connect Method


Read Method

Description

Return data read from the remote server

Visual Basic

[form.]control.Read buffer$, length

Remarks

This method returns data that has been read from the remote server, up to the number of bytes specified. If no data is available to be read, an error will be generated if the control is non-blocking mode. If the control is in blocking mode, the program will stop until data is returned by the server or the connection is closed. Note that it is possible for the returned data to contain embedded null characters.

The buffer argument specifies the string that the data will be copied into.

The length argument specifies the number of bytes to read.

Return Value

The number of bytes actually read from the server is returned by this method, and will cause the RecvLen property to change. If an error occurs, a value of -1 is returned.

See Also

RecvLen Property, RecvNext Property, SendData Property, Read Event


Reset Method

Description

Reset the internal state of the control.

Visual Basic

[form.]control.Reset

Remarks

The Reset method resets the internal state of the control.

Return Value

A value of zero is returned if the control was reset. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Cancel Method


Write Method

Description

Write data to the remote server

Visual Basic

[form.]control.Write buffer$, length

Remarks

This method writes data in the string to the remote server. If the connection is buffered, as is typically the case, the data is copied to the send buffer and control immediately returns to the program. If the control is non-blocking and is out of buffer space, an error will be generated. If the control is blocking, the application will wait until the data can be sent.

The buffer argument specifies the data that should be sent to the remote server. This string may contain embedded null characters.

The length argument specifies the maximum number to bytes to send to the server. After the data has been written, the SendLen property will be updated to reflect the number of bytes actually written. If the control is non-blocking and the send fails because it could not write all of the data to the server, the Write event will be fired when the server can be written to again.

Return Value

This method returns the number of bytes actually written to the server, or -1 if an error was encountered.

See Also

SendLen Property, Timeout Property, Write Event


Common Events
Events


Change Event

Description

The Change event is generated after the contents of a control has changed

Visual Basic

Sub control_Change ( [Index As Integer] )

Remarks

This event is generated when the contents of a control have changed. A Change event can be used to synchronize or coordinate data display among controls.  For example, you can use the Telnet client control's Change event to update a list box which contains selected screen contents.

Note A Change procedure can sometimes cause a cascading event.  This occurs when the control's Change event alters the control's contents, for example, by setting a property in code that determines the control's value, such as the Text property setting for a text box.

See Also

Paint Event, Resize Event


Connect Event

Description

The Connect event is generated when a connection is established.

Visual Basic

Sub control_Connect ( [Index As Integer] )

Remarks

The Connect event is generated when a connection is made with a remote host as a result of a connect action.

See Also

Disconnect Event


Disconnect Event

Description

The Disconnect event is generated when a connection is terminated.

Visual Basic

Sub control_Disconnect ( [Index As Integer] )

Remarks

The Disconnect event is generated when the connection is terminated by the remote host.

See Also

Connect Event


LastError Event

Description

The LastError event is generated when a control error occurs

Visual Basic

Sub control_LastError ([Index As Integer,] ErrorCode As Integer, ErrorString As String, Response As Integer)

Remarks

This event is generated when an error occurs during a control action. Visual Basic errors do not generate this event.

The ErrorCode argument specifies the last control error that has occurred.

The ErrorString argument is a string that describes the error.

The Response argument determines if the error generates a Visual Basic error. The possible values are:

Value	Constant	Description
0	CONTROL_ERRIGNORE	Ignore the error and return as though the operation completed successfully
1	CONTROL_ERRDISPLAY	Return the error to Visual Basic, which may be trapped by the application. This is the default response to the event.
See Also

LastError Property


Paint Event

Description

The Paint event is generated after the control has been repainted

Visual Basic

Sub control_Paint ( [Index As Integer] )

Remarks

This event is generated after a control has been repainted, such as when the control window is resized or a window on top of it has been removed.

Note Using a Paint event procedure for certain tasks can cause a cascading event.  In general, avoid using a Paint procedure for the following:
• Moving or sizing a form or control

• Changing any variables that affect size or visual appearance such as setting an object's BackColor property

• Invoking a Refresh method

A Resize event procedure may be more appropriate for some of these tasks.

See Also

Change Event, Resize Event


Read Event

Description

The Read event is generated when data is available to be read.

Visual Basic

Sub control_Read ([Index As Integer,] DataLength As Integer)

Remarks

The Read event is generated for non-blocking sockets when data is available to be read from the server.

The DataLength argument specifies the number of bytes that can be read from the server.

Note  It is possible for the RecvNext property to return a value greater than DataLength if additional data has been written to the socket while executing code inside the event.

See Also

IsReadable Property, Write Event


Resize Event

Description

The Resize event is generated after the control has been resized

Visual Basic

Sub control_Resize ( [Index As Integer] )

Remarks

This event can be used to move or resize other controls when the browser is resized. You can also use the Resize event to recalculate the width and/or height of controls that depend on the size of the browser window.

See Also

Change Event, Paint Event


Write Event

Description

The Write event is generated when data can be written to the server.

Visual Basic

Sub control_Write ( [Index As Integer] )

Remarks

The Write event is generated for non-blocking sockets when data can be written to the server after a previous attempt failed because it would cause the control to block.

See Also

IsWritable Property, Read Event


Cancel Event

Description

The Cancel event is generated when a blocking operation is canceled

Visual Basic

Sub Socket_Cancel ([Index As Integer])

Remarks

This event is generated when a blocking operation, such as establishing a connection with a remote host, has been canceled. Refer to the Action property for the specified control or the Cancel method to cancel a blocking operation.

See Also

Action Property, IsBlocked Property, LastError Property, Cancel Method


Windows Sockets Errors
Error Messages

The error codes listed here are based on Windows Sockets errors (which, in turn, are based on the error codes that are returned by the Berkeley sockets implementation). The base error value has been increased by 14000 to be compatible with Visual Basic.

Value	Constant	Description
24004	WSAEINTR	Blocking function was canceled
24009	WSAEBADF	Invalid socket descriptor passed to function
24013	WSAEACCES	Access denied
24014	WSAEFAULT	Invalid address passed to function
24022	WSAEINVAL	Invalid socket function call
24024	WSAEMFILE	No socket descriptors are available
24035	WSAEWOULDBLOCK	Socket would block on this operation
24036	WSAEINPROGRESS	Blocking function in progress
24037	WSAEALREADY	Function being canceled has already completed
24038	WSAENOTSOCK	Invalid socket descriptor passed to function
24039	WSAEDESTADDRREQ	Destination address is required
24040	WSAEMSGSIZE	Datagram was too large to fit in specified buffer
24041	WSAEPROTOTYPE	Specified protocol is the wrong type for this socket
24042	WSAENOPROTOOPT	Socket option is unknown or unsupported
24043	WSAEPROTONOSUPPORT	Specified protocol is not supported
24044	WSAESOCKTNOSUPPORT	Specified socket is not supported in this address family
24045	WSAEOPNOTSUPP	Socket operation is not supported
24046	WSAEPFNOSUPPORT	Specified protocol family is not supported
24047	WSAEAFNOSUPPORT	Specified address family is not supported by this protocol
24048	WSAEADDRINUSE	Specified address is already in use
24049	WSAEADDRNOTAVAIL	Specified address is not available
24050	WSAENETDOWN	Network subsystem has failed
24051	WSAENETUNREACH	Network cannot be reached from this host
24052	WSAENETRESET	Network dropped connection on reset
24053	WSAECONNABORTED	Connection was aborted due to timeout or other failure
24054	WSAECONNRESET	Connection was reset by remote network
24055	WSAENOBUFS	No buffer space is available
24056	WSAEISCONN	Socket is already connected
24057	WSAENOTCONN	Socket is not connected
24058	WSAESHUTDOWN	Socket connection has been shut down
24060	WSAETIMEDOUT	Operation timed out before completion
24061	WSAECONNREFUSED	Connection refused by remote network
24064	WSAEHOSTDOWN	Remote host is down
24065	WSAEHOSTUNREACH	Remote host is unreachable
24091	WSAESYSNOTREADY	Network subsystem is not ready for communication
24092	WSAEVERNOTSUPPORTED	Requested version is not available
24093	WSAENOTINITIALIZED	Windows sockets library not initialized
25001	WSAHOST_NOT_FOUND	Authoritative Answer Host not found
25002	WSATRY_AGAIN	Non-Authoritative Answer Host not found
25003	WASNO_RECOVERY	Non-recoverable error
25004	WSANO_DATA	No data record of requested type


WSAEINTR

Blocking function was canceled

This error is generated whenever a blocking socket operation is canceled by setting the Action property to the appropriate value or by using the Cancel method. Note that the Cancel event is fired when a blocking operation is canceled, and the generation of this error depends on how the application responds to this event.


WSAEBADF

Invalid socket descriptor passed to function

This error is generated when a socket operation is being performed on an invalid socket. Before the socket can be used, the Action property must be used to create the socket.


WSAENOTSOCK

Invalid socket descriptor passed to function

This error is generated when a socket operation is being performed on an invalid socket. Before the socket can be used, the Action property must be used to create the socket.


WSAEACCES

Access denied

This error is generated when data is being written to a broadcast address, but the appropriate flags are not set. This error should never be generated by the control.


WSAEFAULT

Invalid address passed to function

This error is generated when an invalid address to an internal data structure is passed to a socket function. This error should never occur with the control.


WSAEINVAL

Invalid socket function call

This error is generated when an invalid argument is passed to a socket function. It should never occur when using the control.


WSAEMFILE

No socket descriptors are available

This error is generated when an application attempts to create another socket, and no more socket connections can be created. Note that the maximum number of open sockets is determined by the underlying socket library, not the control.


WSAEWOULDBLOCK

Socket would block on this operation

This error is generated when an application attempts to perform an operation on the socket, such as receiving data, that would cause the socket to block. This error is only generated for non-blocking sockets, or in some cases, blocking sockets that had a blocking function canceled.


WSAEINPROGRESS

Blocking function in progress

This is error is generated when an application attempts to perform some socket operation when either that same socket, or another socket created by the same task, is blocked. For example, consider the following scenario:

The application attempts to read data from the socket. However, since there is no data to be read, it blocks waiting for data to arrive. This causes the control to go into a message loop which allows the application to respond to events.

The user presses a button that generates an event which attempts to write data to the socket. Since this event occurred while the socket is still blocked waiting for data to be received, the WSAEINPROGRESS error is generated.

Other combinations are possible. To determine if a specific socket is blocked, the IsBlocked property can be read. If it is blocked, the State property will report what blocking function the socket is executing.


WSAEALREADY

Function being canceled has already completed

The Action property was set to cancel a blocking operation, but the operation has already completed.


WSAEDESTADDRREQ

Destination address is required

This error is generated when a connection is attempted, but no host name or address has been specified.


WSAEMSGSIZE

Datagram was too large to fit in specified buffer

This error is generated for sockets of type SOCK_DGRAM when the amount data being written to the socket is too large. This error will only be generated by the Windows Sockets control.


WSAEPROTOTYPE

Specified protocol is the wrong type for this socket

This error is generated when a socket is created with incompatible SocketType and Protocol properties. For example, the IPPROTO_UDP protocol is not compatible with a SOCK_STREAM type socket.


WSAENOPROTOOPT

Socket option is unknown or unsupported

This error is generated when an invalid option is set for a socket. Since the controls will silently ignore socket options that are not supported, this error should not be generated.


WSAEPROTONOSUPPORT

Specified protocol is not supported

This error is generated when the Protocol property is set to an illegal value, or to a protocol that is not supported by the underlying socket library. The Windows Sockets specification only guarantees that the IPPROTO_TCP and IPPROTO_UDP protocols will be supported.


WSAESOCKTNOSUPPORT

Specified socket type is not supported by this protocol

This error is generated when the control attempts to use a socket type that is not supported by the underlying socket library for the given protocol.  If this error is generated by the Ping control, it indicates that the stack does not support raw sockets, a special type of socket that is required to send ICMP echo datagrams. Not all stacks support raw sockets because it is not part of the Windows Sockets 1.1 specification. Most notably, Microsoft TCP/IP for Windows 3.11, Windows 95 and Windows NT does not support raw sockets.


WSAEOPNOTSUPP

Socket operation is not supported

This error is generated when an invalid socket operation is performed, such as attempting to write urgent data on datagram socket.


WSAEPFNOSUPPORT

Specified protocol family is not supported

This error occurs when an invalid or unsupported protocol family is specified, and should never be generated by the control.


WSAEAFNOSUPPORT

Specified address family is not supported by this protocol

This error is generated when the AddressFamily property is set to an illegal value, or to a value not supported by the underlying socket library. The Windows Sockets specification only guarantees that the AF_INET address family will be supported.


WSAEADDRINUSE

Specified address is already in use

This error is generated when an application attempts to create a listening socket and specifies an address that is in use, or if the socket is already listening for connections. This error can also occur if the LocalPort property was set to a value of IPPORT_ANY and no ports are available.


WSAEADDRNOTAVAIL

Specified address is not available

This error occurs when an application attempts to connect to a remote host, and the address is not available from the local system.


WSAENETDOWN

Network subsystem has failed

This error is generated when the Windows Sockets library has detected a failure in the underlying protocol stack. If this error occurs frequently, contact your network software vendor.


WSAENETUNREACH

Network cannot be reached from this host

This error occurs when the Windows Sockets library cannot establish a connection with the specified remote host.


WSAENETRESET

Network dropped connection on reset


WSAECONNABORTED

Connection was aborted due to timeout or other failure

This error is generated when the remote host aborts the connection due to a timeout or some other failure.


WSAECONNRESET

Connection was reset by remote network

This error is generated when the remote host resets the connection.


WSAENOBUFS

No buffer space is available

This error is generated when the Windows Sockets library determines that it does not have enough buffer space to establish a connection. This error is not generated if the control cannot allocate enough memory for it's own internal buffers.


WSAEISCONN

Socket is already created

This error is generated if the application attempts to connect or listen on a socket that is already connected to a remote host.


WSAENOTCONN

Socket is not connected

This error is generated when an application attempts to perform an operation on a socket that is not connected to a remote host, where such a connection is required. For example, attempting to write data to a SOCK_STREAM socket that has been created but not connected.


WSAESHUTDOWN

Socket connection has been shut down

This error is generated when an application attempts to read or write on a socket that has been shut down. Note that a socket can be shut down by setting the Shutdown property.


WSAETIMEDOUT

Operation timed out before completion

This error is generated when a blocking socket operation times out before it has completed. The amount of time that the control waits until a timeout occurs is determined by the Timeout property.


WSAECONNREFUSED

Connection refused by remote network

This error occurs when the remote system rejects your attempt to connect with it, either because no server is listening on the specified port or it's unable to accept any additional connections.


WSAEHOSTDOWN

Remote host is down


WSAEHOSTUNREACH

Remote host is unreachable


WSAESYSNOTREADY

Network subsystem is not ready for communication

This error occurs when the Windows Sockets library determines that the underlying protocol stack is not ready or unavailable. This error should never be generated by the control.


WSAEVERNOTSUPPORTED

Requested version is not available

This error occurs when the control attempts to initialize the Windows Sockets library, and the initialization fails because it does not support the 1.1 specification.


WSAENOTINITIALIZED

Windows Sockets library is not initialized

This error occurs when a program calls a socket function but has not yet initialized the Windows Sockets library. The library is initialized only after the HostAddress, HostName, RemotePort or RemoteService properties are set by the application, or when a connection attempt is made.


WSAHOST_NOT_FOUND

Authoritative Answer Host not found

This error occurs when a database function, such as resolving an internet address into a host name, fails. This error may indicate a configuration problem with the underlying protocol stack.


WSATRY_AGAIN

Non-Authoritative Host not found

This error occurs when a database function, such as resolving an internet address into a host name, fails. This error may indicate a configuration problem with the underlying protocol stack.


WSANO_RECOVERY

Non-recoverable error occured

This error occurs when a database function, such as resolving an internet address into a host name, fails. This error may indicate a configuration problem, or a problem with the remote server.


WSANO_DATA

No data of requested type

This error occurs when a database function, such as resolving an host name into an internet address, fails. This is typically a configuration or data entry problem, such as an invalid host name or non-existent service.


 Domain Name Service Control
Properties       Methods      Events      Errors

Description

The Domain Name Service control enables the developer to query a remote name server. This can be used to resolve host names to Internet addresses, determine the target system type and the services that it supports.

File Name

CSDNSCTL.VBX, CSDNS16.OCX, CSDNS32.OCX

Object Type

DnsClient

Remarks

The Domain Name Service provides a way for client applications to resolve host names into IP addresses, as well as provide additional information about the host. Typically, the addresses of one or more nameservers (systems who provide this information to clients) are configured in the client's TCP/IP stack. The DNS control allows an application to query one or more nameservers directly, without depending on the configuration of the client system.

In addition to resolving host names and IP addresses, the DNS control can be used to determine what services the remote host provides, and the type of system (if this information has been specified).

Requirements

The DNS control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the DNS control, you should install the appropriate  file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


DNS Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*IsBlocked	Name	*Timeout
*HostAddress	*LastError	*NameServer	Top
*HostInfo	Left	*RemotePort	*Vendor
*HostName	*Library	*RemoteService	*Version
*HostProtocol	*LocalAddress	*Retry
*HostServices	*LocalDomain	*ServerAddress
Index	*LocalName	Tag


DNS Action Property
Action Property

Description

Setting this property causes the control to take some action, such as canceling the current operation or resetting it's internal state.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	DNS_ACTION_CANCEL	Cancel the current blocking operation and return control to the application.
2	DNS_ACTION_RESET	Reset the state of the control, removing all nameservers from it's internal table.
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Connected Property, Timeout Property


DNS HostAddress Property
HostAddress Property

Description

Set or return the IP address of the remote host.

Visual Basic

[form.]control.HostAddress [= addr$]

Remarks

Setting the HostAddress property causes the control to submit a reverse query to the nameservers that you have specified. If a reverse entry is found for the IP address, the HostName property is changed to that host name.

Note that reverse DNS entries may not be available for many systems.

Data Type

String

See Also

HostName Property, NameServer Property


DNS HostInfo Property
HostInfo Property

Description

Returns information about the host system.

Visual Basic

[form.]control.HostInfo

Remarks

The HostInfo property returns a string that includes the machine type and operating system for the host. This information corresponds to it's HINFO record in the database.

Data Type

String

See Also

HostAddress Property, HostName Property, HostProtocol Property, HostServices Property


DNS HostName Property
HostName Property

Description

Set or return the name of the remote host.

Visual Basic

[form.]control.HostName [= hostname$]

Remarks

The HostName property should be set to the name of the remote system that you wish to obtain information on. Setting this property causes a query to be submitted to the nameservers that you have specified. If the host name can be resolved, the HostAddress property is set to the IP address of the host, in dot-notation.

Data Type

String

See Also

HostAddress Property, NameServer Property


DNS HostServices Property
HostServices Property

Description

Return the well-known services available for the specified host.

Visual Basic

[form.]control.HostServices

Remarks

The HostServices property returns a string that contains a list of well-known services for the specified host. This corresponds to the WKS entry in the nameserver's database. The services returned depend on the protocol specified in the HostProtocol property.

Data Type

String

See Also

HostProtocol Property


DNS HostProtocol Property
HostProtocol Property

Description

Set the protocol to return service information for the specified host.

Visual Basic

[form.]control.HostProtocol [= proto]

Remarks

The HostProtocol property determines the protocol for which service information is returned, and should be set to one of the following values:

Value	Constant	Description
6	IPPROTO_TCP	Specifies services using the Transmission Control Protocol (TCP).
17	IPPROTO_UDP	Specifies services using the User Data Protocol (UDP).
Data Type

Integer

See Also

HostServices Property


DNS LocalDomain Property
LocalDomain Property

Description

Set or return the domain name for the local system

Visual Basic

[form.]control.LocalDomain [ = domain$ ]

Remarks

The LocalDomain property is used to set the domain name for the local host. The local domain name is used when the name assigned to HostName property does not specify a domain (in other words, does not have a dot in the name). In that case, the value of the LocalDomain property is appended to the hostname.

If a domain name has been specified for the local system, the LocalDomain property is set to that value by default.

Data Type

String

See Also

HostAddress Property, HostName Property


DNS NameServer Property
NameServer Property

Description

Set or return the IP address of a nameserver.

Visual Basic

[form.]control.NameServer(index) [ = address$ ]

Remarks

The NameServer property array is used to specify one or more nameservers used to resolve hostnames and addresses. The address value must be an IP address in dot notation. The index argument specifies which nameserver to set or return a value for. There may be up to 3 nameservers defined for any single instance of the control.

Data Type

String

See Also

HostAddress Property, HostName Property, Retry Property


DNS Retry Property
Retry Property

Description

Set the number of times the control attempts to resolve a hostname.

Visual Basic

[form.]control.Retry [ = count ]

Remarks

The Retry property specifies the number of times, per nameserver, that the control attempts to resolve a hostname or address. If attempts to query a nameserver fail, the control waits a period of time and then resubmits the query. As the number of retries increase, the longer the period of time the control waits to receive a response before attempting the query using another nameserver.

The default number of retries is four, with a minimum value of one and a maximum value of eight.

Data Type

Integer

See Also

NameServer Property


DNS ServerAddress Property
ServerAddress Property

Description

Return the address of the nameserver that resolved the query.

Visual Basic

[form.]control.ServerAddress

Remarks

The ServerAddress property returns the IP address (in dot notation) of the nameserver that resolved the previous query.

Data Type

String

See Also

HostAddress Property, HostName Property, HostProtocol Property


DNS Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*Reset
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


DNS Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*LastError


FTP Control
 File Transfer Protocol Control
Properties      Methods      Events      Errors

Description

The File Transfer Protocol client control allows the developer to establish a connection with a host and exchange files between the local and remote system.

File Name

CSFTPCTL.VBX, CSFTP16.OCX, CSFTP32.OCX

Object Type

FtpClient

Remarks

The FTP control allows the developer to connect to a remote server and perform file and directory maintenance functions. In addition to copying files between the local and remote host, the control can be used to list the files on the remote system, remove and rename files, create and remove directories and perform other server-specific functions.

Requirements

The FTP control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the FTP control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


FTP Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Account	*HostName	*LocalName	*RenamedFile	Top
*Action	Index	Name	*ResultCode	*TransferBytes
*AutoResolve	*IsBlocked	*Passive	*ResultString	*TransferTime
*Binary	*IsClosed	*Password	*SendData	*UserName
*Blocking	*IsReadable	*RecvData	*SendLen	*Vendor
*Command	*IsWritable	*RecvLen	*Socket	*Verbose
*Connected	*LastError	*RecvNext	*SocketError	*Version
*FileMask	Left	*RemoteDir	*State
*FileType	*Library	*RemoteFile	*System
*Handle	*LocalAddress	*RemotePort	Tag
*HostAddress	*LocalFile	*RemoteService	*Timeout


FTP Account Property
Account Property

Description

The account name for the current user.

Visual Basic

[form.]control.Account [= account$]

Remarks

The Account property specifies the account name of the current user, if it is required by the server for authentication.

Note  Not all servers require an account name, in which case this property is ignored.

Data Type

String

See Also

Password Property, UserName Property


FTP Action Property
Action Property

Description

Setting this property causes the FTP client to take some action, such as connecting to a server, transferring a file or creating a directory.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the client may take:

Value	Constant	Description
1	FTP_ACTION_CONNECT	Connect to the remote FTP host specified by the HostAddress or HostName property.
2	FTP_ACTION_LOGIN	Login to the FTP server as the user specified by the UserName, Password and Account properties.
3	FTP_ACTION_LOGOUT	Logoff the FTP server, but remain connected. The action must be used before the client  can login as a different user.
4	FTP_ACTION_DISCONNECT	Logout the current user and disconnect from the remote server.
5	FTP_ACTION_GETFILE	Copy the file specified by the RemoteFile property from the server to the local system.
6	FTP_ACTION_PUTFILE	Copy the file specified by the LocalFile property to the server from the local system.
7	FTP_ACTION_FILELIST	Retrieve the list of files in the current working directory.
8	FTP_ACTION_OPEN	Open the file specified by the RemoteFile property for reading. If the file does not exist, an error is returned.
9	FTP_ACTION_CREATE	Create the file specified by the RemoteFile property on the server. If the file exists, it is overwritten.
10	FTP_ACTION_APPEND	Open the file specified by the RemoteFile property for writing. If the file exists, then data is appened to it, otherwise the file is created.
11	FTP_ACTION_CLOSE	Close the remote file that has been opened or created.
12	FTP_ACTION_CANCEL	Cancel any blocking operation and terminate the current file transfer, if one is in progress.
13	FTP_ACTION_DELETE	Delete the file specified by the RemoteFile property from the server system.
14	FTP_ACTION_RENAME	Rename the file specified by the RemoteFile property on the server system.
15	FTP_ACTION_GETCWD	Return the current working directory on the server into the RemoteDir property.
16	FTP_ACTION_CHDIR	Change the current working directory on the server to the directory specified in the RemoteDir property.
17	FTP_ACTION_MKDIR	Create the directory specified by the RemoteDir property.
18	FTP_ACTION_RMDIR	Remove the directory specified by the RemoteDir property.
19	FTP_ACTION_RESET	Reset the command connection to the remote server
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Connected Property, FileType Property, LocalFile Property, RemoteDir Property, RemoteFile Property,State Property, Timeout Property


FTP Binary Property
Binary Property

Description

Enable the transfer of binary data files

Visual Basic

[form.]control.Binary [= { True | False }]

Remarks

The Binary property specifies the transfer mode used when copying files between the local and remote host. It is included for compatibilty only. Applications should use the FileType property instead.

Data Type

Integer (Boolean)

See Also

FileType Property, LocalFile Property, RemoteFile Property


FTP Command Property
Command Property

Description

Specify a command to execute on remote host.

Visual Basic

[form.]control.Command [ = ftpcmd$ ]

Remarks

Setting the Command property causes the specified command to be executed on the server. This allows the application to take advantage of extended commands that are not directly available through the control. The ResultCode property should be checked to determine if the command was successful or not.

Data Type

String

See Also

ResultCode Property, ResultString Property


FTP LocalFile Property
LocalFile Property

Description

Set or return the local file name.

Visual Basic

[form.]control.LocalFile [= filename$]

Remarks

The LocalFile property specifies a file name on the local system, and is used with the FTP_ACTION_GETFILE and FTP_ACTION_PUTFILE properties.

Data Type

String

See Also

Action Property, RemoteFile Property, RenamedFile Property, GetFile Method, PutFile Method, Progress Event


FTP Passive Property
Passive Property

Description

Enable passive file transfers.

Visual Basic

[form.]control.Passive  [= { True | False } ]

Remarks

The Passive property enables or disables passive file transfers between the local and remote host. In passive transfer mode, the client is responsible for establishing the data connection between the remote server and the local system. By default, transfers are not passive, with the server establishing the data connection with the client system.

Note Not all servers support passive file transfers. If the Passive property is set and the server does not support passive mode, an error will be returned the next time a file transfer is attempted.

Data Type

Integer (Boolean)

See Also

Action Property


FTP RemoteDir Property
RemoteDir Property

Description

Set or return the name of a directory on the remote host.

Visual Basic

[form.]control.RemoteDir [= account$]

Remarks

The RemoteDir property specifies the name of a directory on the remote host. When a connection is first established with the FTP server, this property is set to the current working directory. Remote directories may be changed, created or removed by using this property in conjunction with an action code.

Data Type

String

See Also

Action Property, ChangeDirectory Method


FTP RemoteFile Property
RemoteFile Property

Description

Set or return the remote file name.

Visual Basic

[form.]control.LocalFile  [= filename$]

Remarks

The  RemoteFile property specifies a file name on the remote system, and is used with the FTP_ACTION_GETFILE and FTP_ACTION_PUTFILE properties.

Data Type

String

See Also

Action Property, LocalFile Property, RenamedFile Property, GetFile Method, PutFile Method, Progress Event


FTP RenamedFile Property
RenamedFile Property

Description

Set or return the new name of a remote file.

Visual Basic

[form.]control.RenamedFile [= filename$]

Remarks

The RenamedFile property is used in conjunction with the RENAME action to rename a file on the remote server. The current file name is assigned to the RemoteFile property, and the new file name is assigned to the RenamedFile property.

Data Type

String

See Also

Action Property, LocalFile Property, RemoteFile Property


FTP State Property
State Property

Description

Return the current state of the control.

Visual Basic

[form.]control.State

Remarks

The State read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	FTP_CLIENT_UNUSED	No connection established
1	FTP_CLIENT_IDLE	Client connection is not active
2	FTP_CLIENT_CONNECTING	Establishing connection with server
3	FTP_CLIENT_LOGIN	Logging user into server
4	FTP_CLIENT_TRANSFER	File transfer in progress
Data Type

Integer

See Also

IsBlocked Property


FTP System Property
System Property

Description

Return information about the remote host.

Visual Basic

[form.]control.System

Remarks

The System property contains information about the remote host operating system.

Data Type

String


FTP TransferBytes Property
TransferBytes Property

Description

Return the number of bytes transferred from the remote server.

Visual Basic

[form.]control.TransferBytes

Remarks

The TransferBytes property returns the number of bytes that have been copied to or from the remote FTP server. If this property is read while a transfer is ongoing, the property returns the number of bytes that have been copied up to that point. If read after a transfer has completed, the total number of bytes copied is returned. This property is reset with every data transfer.

Data Type

Long

See Also

TransferTime Property, Progress Event


FTP TransferTime Property
TransferTime Property

Description

Return the number of milliseconds elapsed during a data transfer.

Visual Basic

[form.]control.TransferTime

Remarks

The TransferTime returns the number of milliseconds that have elapsed since the data connection was opened on the remote server. If the property is read while a transfer is ongoing, it returns the elapsed time. If the property is read after the transfer is complete, it returns the total number of milliseconds it took to transfer the data. This property value is reset with every data transfer.

Data Type

Long

See Also

TransferBytes Property, Progress Event


FTP Verbose Property
Verbose Property

Description

Enable verbose directory listings from the remote host.

Visual Basic

[form.]control.Verbose  [= { True | False } ]

Remarks

The Verbose property enables or disables "verbose" directory listings from the remote host. If True, then information about file ownership, permissions, size, etc. are returned to the client. If False, only the file names are returned. This property is used in conjunction with the FTP_ACTION_FILELIST action.

Data Type

Integer (Boolean)

See Also

Action Property, RemoteDir Property


FTP FileType Property
FileType Property

Description

Set or return the current file transfer type

Visual Basic

[form.]control.FileType = [ ftype% ]

Remarks

The FileType property specifes the type of file transfer between the local and remote host. The file transfer types supported are:

Value	Constant	Description
0	FILE_TYPE_ASCII	The file being transferred is an ASCII file. The characters the mark the end of a line (for example, a carriage return/linefeed pair under MS-DOS) are automatically converted to the format used by the target operating system.
1	FILE_TYPE_EBCDIC	The file being transferred is a text file created using the EBCDIC character set. If a file is being copied to a remote system, the ASCII characters are automatically converted to EBCDIC. If the file is being retrieved from a remote system, the EBCDIC characters are automatically converted to ASCII.
2	FILE_TYPE_IMAGE	The file is transferred without any modification. This is the default file transfer type, and should be used when transferring binary (non-text) data.
This property should be used in place of the Binary property, which was included for compatibilty purposes. Setting the property to FILE_TYPE_IMAGE is the same as setting Binary to True.

Data Type

Integer

See Also

Binary Property, LocalFile Property, RemoteFile Property


FTP FileMask Property
FileMask Property

Description

Set or return the remote file list mask

Visual Basic

[form.]control.FileMask  [=wildcard$]

Remarks

This property determines the list of filenames that are returned by the remote server using the FTP_ACTION_FILELIST action. An empty string, the default value, indicates that all files in the current directory should be listed by the control. Typically, this property is set to a wildcard mask that limits the number of files returned by the server. For example, to return only those files that end in a .DAT extension, the property could be set to the value "*.DAT"

Note The type of wildcards which may be used depend on the server and the type of file system that it is using. Take particular care when dealing with file systems that distinguish between upper- and lower-case letters in a filename. The value of this property does not affect the FileList method.

Data Type

String

See Also

Action Property, RemoteDir Property, FileList Method


FTP Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*DeleteFile	*Logout	*RemoveDirectory
*ChangeDirectory	*Disconnect	*MakeDirectory	*RenameFile
*CloseFile	*FileList	*OpenFile	*Reset
*Connect	*GetFile	*PutFile	*Write
*CreateFile	*Login	*Read
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later


FTP ChangeDirectory Method
ChangeDirectory Method

Description

Return data read from the remote server.

Visual Basic

[form.]control.ChangeDirectory path$

Remarks

The ChangeDirectory method changes the current working directory on the remote server. This method updates the RemoteDir property to reflect the new path.

The path argument specifies the directory on the remote server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, RemoteDir Property


FTP CloseFile Method
CloseFile Method

Description

Close the remote file that was opened for reading or writing.

Visual Basic

[form.]control.CloseFile

Remarks

The CloseFile method closes the file that was created using the CreateFile method, or opened for reading using the OpenFile method.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, CreateFile Method, OpenFile Method


FTP CreateFile Method
CreateFile Method

Description

Create a new file or overwrite an existing file.

Visual Basic

[form.]control.CreateFile filename$

Remarks

The CreateFile method creates a new file on the remote server using the specified file name. The Write method may then be used to copy data to the open file.

The filename argument specifies the name of the file to create on the remote host.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, CloseFile Method, Write Method


FTP DeleteFile Method
DeleteFile Method

Description

Remove a file on the remote host.

Visual Basic

[form.]control.DeleteFile filename$

Remarks

The DeleteFile method deletes an existing file from the remote server.

Note  You must have the appropriate permission to delete the file, or an error will occur.

The filename argument specifies the name of the file to delete on the remote host.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, RenameFile Method


FTP FileList Method
FileList Method

Description

Return a list of files on the remote host.

Visual Basic

[form.]control.FileList path$, verbose

Remarks

The FileList method instructs the server to return a list of files in the specified directory. The listing is returned on the data channel and may be read using the Read method.

The path argument specifies the directory on the remote host.

The verbose argument is a boolean flag which indicates if a verbose listing is to be returned. If a value of zero is passed, then only the filenames will be returned. A non-zero value indicates that additional information should be returned by the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, FileMask Property, Verbose Property


FTP GetFile Method
GetFile Method

Description

Copy a file from the remote system to the local system.

Visual Basic

[form.]control.GetFile localfile$, remotefile$

Remarks

The GetFile method copies an existing file from the remote system to the local system. If the local file already exists, it is overwritten. This method updates the LocalFile and RemoteFile properties.

The localfile argument specifies the name of the file on the local system. If the file exists, it will be overwritten.

The remotefile argument specifies the name of the file on the remote system. You must have permission to open this file for reading.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, LocalFile Property, RemoteFile Property, Progress Event


FTP Login Method
Login Method

Description

Login to the remote server.

Visual Basic

[form.]control.Login username$, password$

Remarks

The Login method identifies the user to the remote server. If the user name or password is invalid, an error will occur. By default, when a connection is established, the UserName, Password and Account properties are used to automatically log the user in to the server. This method should only be used if you wish to log in as another user during the same session.

The username argument specifies the name of the user to login as.

The password argument specifies the password that authenticates the specified user. Note that the password is passed as clear text to the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Logout Method


FTP Logout Method
Logout Method

Description

Log the current user off the server.

Visual Basic

[form.]control.Logout

Remarks

The Logout method logs the current user off the server. The Login method may then be used to login as another user during the same session. Note that this method will not terminate the connection with the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Login Method


FTP MakeDirectory Method
MakeDirectory Method

Description

Create a new directory on the remote host.

Visual Basic

[form.]control.MakeDirectory newdir$

Remarks

The MakeDirectory method creates a new directory on the remote host. Note that you must have the appropriate permission to create a directory or an error will occur.

The newdir argument specifies the name of the directory to create on the remote host.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, ChangeDirectory Method, RemoveDirectory Method


FTP OpenFile Method
OpenFile Method

Description

Open an existing file or creates a new file on the remote host.

Visual Basic

[form.]control.OpenFile filename$, openmode%

Remarks

The OpenFile method opens an existing file for on the remote server using the specified file name. The Read method may then be used to read data from the file and the Write method may be used to write data to the file.

The filename argument specifies the name of the file to open or create on the remote host.

The openmode argument specifies how the file is to be opened. The following values may be used:

Constant	Value	Description
FTP_FILE_READ	0	Open an existing file for reading.
FTP_FILE_WRITE	1	Create a new file or overwrite an existing file for writing.
FTP_FILE_APPEND	2	Open an existing file for writing. Data written to the file is appened.
Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, CloseFile Method, CreateFile Method, Read Method, Write Method


FTP PutFile Method
PutFile Method

Description

Copy a file from the local system to the remote system.

Visual Basic

[form.]control.PutFile localfile$, remotefile$

Remarks

The PutFile method copies an existing file from the local system to the remote system. If the remote file already exists, it is overwritten. This method updates the LocalFile and RemoteFile properties.

The localfile argument specifies the name of the file on the local system.

The remotefile argument specifies the name of the file on the remote system. You must have permission to create this file. If the file exists, it will be overwritten.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, LocalFile Property, RemoteFile Property, Progress Event


FTP RemoveDirectory Method
RemoveDirectory Method

Description

Remove a directory on the remote host.

Visual Basic

[form.]control.RemoveDirectory directory$

Remarks

The RemoveDirectory method removes an existing directory on the remote host. You must have the appropriate permission to remove the directory, or an error will occur.

The directory argument specifies the name of the directory to remove on the remote host.

Note Most systems will not allow you to remove a directory if it contains files.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, ChangeDirectory Method, MakeDirectory Method


FTP RenameFile Method
RenameFile Method

Description

Change the name of an existing file on the host.

Visual Basic

[form.]control.RenameFile oldname$, newname$

Remarks

The RenameFile method renames an existing file on the remote host to the new name.

Note  You must have permission to change the file name or an error will occur.

The oldname argument specifies the current name of the file on the remote host.

The newname argument specifies the name that the existing file will be changed to.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, DeleteFile Method


FTP Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*Disconnect	*Progress	*Reply
*Connect	*LastError	*Read	*Write


FTP Close Event
Close Event

Description

The Close event is generated when the data connection is closed.

Visual Basic

Sub control_Close ( [Index As Integer] )

Remarks

The Close event is fired when the data connection to the server has been closed. Typically this indicates that the data transfer has completed.

Note This event does not indicate that the control connection between the client and server has been disconnected. This event only indicates the end of a single transfer of data between the client and server.

See Also

Disconnect Event


FTP Progress Event
Progress Event

Description

The Progress event is generated during data transfer.

Visual Basic

Sub control_Progress ([Index As Integer,] BytesCopied As Long, FileLength As Long, Percent As Integer)

Remarks

The Progress event is generated during the transfer of data between the client and FTP server, indicating the amount of data exchanged. For transfers of large amounts of data, this event can be used to update a progress bar or other user-interface control to provide the user with some visual feedback.

The BytesCopied argument specifies the number of bytes that have been transferred between the client and remote host.

The FileLength argument specifies the size of the file being transferred. This value may be zero if the remote server does not support the SIZE command, which returns the size of a remote file.

The Percent argument is an integer with a value between 0 and 100 which specifies the percentage of data that's been transferred.

Note This event is only fired when using the GETFILE or PUTFILE actions. It will not be fired when reading or writing data using the RecvData or SendData properties.

See Also

Action Property, TransferBytes Property, TransferTime Property


FTP Reply Event
Reply Event

Description

The Reply event is generated when the client receives a reply from the server.

Visual Basic

Sub control_Reply ( [Index As Integer], ResultCode As Integer, ResultString As String )

Remarks

The Reply event is generated when the client receives a reply from the server after some action has been taken. The ResultCode argument contains the numeric result code returned by the server. The result codes returned from an FTP server fall into one of the following catagories:

Value	Description
100-199	Positive preliminary result. This indicates that the requested action is being initiated, and the client should expect another reply from the server before proceeding.
200-299	Positive completion result. This indicates that the server has successfully completed the requested action.
300-399	Positive intermediate result. This indicates that the requested action cannot complete until additional information is provided to the server.
400-499	Transient negative completion result. This indicates that the requested action did not take place, but the error condition is temporary and may be attempted again.
500-599	Permanent negative completion result. This indicates that the requested action did not take place.
The ResultString argument contains the descriptive string returned by the server which describes the result. The string contents may vary depending on the type of remote server.

See Also

Action Property, ResultCode Property, ResultString Property


FTP Control Errors
 Value                   Description

    22001                   No free handles
    22002                   Cannot allocate memory
    22003                   Not session owner
    22004                   Cannot initialize network
    22005                   Invalid host name
    22006                   Cannot create socket
    22007                   Cannot accept connection
    22008                   Cannot connect to server
    22009                   Cannot get peer information
    22010                   Cannot bind socket
    22011                   Cannot listen for connection
    22012                   Invalid parameter passed to function
    22013                   Invalid handle passed to function
    22014                   Cannot select socket
    22015                   Cannot read socket
    22016                   Cannot write socket
    22017                   End of data
    22018                   Connection in use
    22019                   Connection not in use
    22020                   Timeout on socket operation"
    22021                   Internal synchronization error
    22022                   Remote server closed connection
    22023                   Remote server is not ready, try again
    22024                   Remote server is not available
    22025                   Unknown problem with remote server
    22026                   Unable to create data connection
    22027                   Data connection already open
    22028                   Data connection is closed
    22029                   File transfer aborted
    22030                   Data connection is read-only
    22031                   Data connection is write-only
    22032                   Unable to set file type
    22033                   Data connection is passive
    22034                   Cannot determine server address
    22035                   Cannot create local file
    22036                   Cannot open local file
    22037                   Cannot read local file
    22038                   Cannot write local file
    22039                   Cannot login to remote server
    22040                   Cannot open data connection
    22041                   Remote file unavailable
    22042	                   Insufficient storage space
    22043                   Command not recognized
    22044                   Invalid command argument
    22045                   Command not implemented
    22046                   Invalid command sequence
    22047                   Not logged in on server
    22048                   Account required for storing files
    22049                  Cannot access file on server
    22050                  File exceeded storage allocation
    22051                  Invalid file name
    22052                  Unexpected server error


Ping Control
 ICMP Echo Control
Properties      Methods      Events      Errors

Description

The control sends Internet Control Message Protocol echo (ping) packets to a remote host to determine if that host is reachable over the network.

File Name

CSPING.VBX, CSPING16.OCX, CSPING32.OCX

Object Type

Ping

Requirements

The ping control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. This control will not function unless the library supports raw sockets. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the ping control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


Ping Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	Index	*LocalName	Tag
*AutoResolve	*Interval	Name	*Timeout
*Blocking	*LastError	*PacketSize	Top
Enabled	Left	*RecvCount	*TripAverage
*HostAddress	*Library	*Reset	*TripMaximum
*HostName	*LocalAddress	*SendCount	*TripMinimum


Ping Action Property
Action Property

Description

Setting this property causes the control to take some action.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	PING_ACTION_ECHO	Send an ICMP echo datagram to the host
2	PING_ACTION_CANCEL	Cancel the blocking operation
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Interval Property, Reset Property


Ping Interval Property
Interval Property

Description

Set or return the number of milliseconds between ICMP echo packets

Visual Basic

[form.]control.Interval [= msecs ]

Remarks

The Interval property determines the number of milliseconds the control waits until an ICMP echo packet is sent to the target system. If the interval is set to 0, no more packets are sent.

Data Type

Integer

See Also

Action Property, PacketSize Property, SendCount Property, RecvCount Property, Echo Event, Reply Event


Ping PacketSize Property
PacketSize Property

Description

Set or return the size of an ICMP echo packet

Visual Basic

[form.]control.PacketSize [= bytes ]

Remarks

The PacketSize property determines the size of an ICMP echo packet. By default, the packet is 64 bytes in length. The minimum packet size is 8 bytes, and the maximum size is 512 bytes.

Data Type

Integer

See Also

Action Property, Interval Property


Ping RecvCount Property
RecvCount Property

Description

Returns the number of packets that have been received

Visual Basic

[form.]control.RecvCount

Remarks

The RecvCount property returns the number of packets that have been echoed back from the remote system.

Data Type

Integer

See Also

SendCount Property


Ping Reset Property
Reset Property

Description

Set or return the amount of time until a blocking operation fails

Visual Basic

[form.]control.Reset = True

Remarks

Setting the Reset property to True causes the send, receive and trip statistics to be reset to zero and cancels any blocking socket operation.

Data Type

Integer (Boolean)

See Also

RecvCount Property, SendCount Property, TripAverage Property, TripMaximum Property, TripMinimum Property


Ping SendCount Property
SendCount Property

Description

Returns the number of packets that have been sent

Visual Basic

[form.]control.SendCount

Remarks

The SendCount property returns the number of packets that have been echoed to the remote system.

Data Type

Integer

See Also

RecvCount Property


Ping Timeout Property
Timeout Property

Description

Set or return the amount of time until a ICMP echo fails

Visual Basic

[form.]control.Timeout [= msecs ]

Remarks

Setting this property specifies the number of milliseconds until an ICMP echo  fails and the control generates a Timeout event.

Data Type

Long

See Also

Timeout Event


Ping TripAverage Property
TripAverage, TripMaximum, TripMinimum Property

Description

Returns packet trip times in milliseconds

Visual Basic

[form.]control.TripAverage
[form.]control.TripMaximum
[form.]control.TripMinimum

Remarks

The TripAverage property returns the average number of milliseconds for an ICMP echo packet to be returned from the remote host. The TripMaximum property returns the longest trip time for any packet, and the TripMinimum property returns the shortest trip time.

Data Type

Long

See Also

Interval Property, RecvCount Property, SendCount Property


Ping Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*Echo
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


Ping Echo Method
Echo Method

Description

Send an ICMP echo datagram to the specified host

Visual Basic

[form.]control.Echo

Remarks

This method sends a single ICMP echo datagram to the host specified by the HostAddress or HostName property.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Ping Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Echo	*LastError	*Reply	*Timeout


Ping Echo Event
Echo Event

Description

The Echo event is generated when a packet is sent to the remote host

Visual Basic

Sub control_Echo ( [Index As Integer] )

Remarks

This event is generated for non-blocking sockets when an ICMP echo packet is sent to the remote host.

See Also

Reply Event


Ping Reply Event
Reply Event

Description

The Reply event is generated when a packet is received

Visual Basic

Sub control_Reply ([Index As Integer,] Sequence As Integer, Bytes As Integer, Elapsed As Long)

Remarks

This event is fired when a packet is echoed back from the remote system. There is no guarantee that packets will be returned in the sequence they were sent (or that they will be returned at all).

The Sequence argument contains the packet sequence number, which is used to uniquely identify each packet that is sent to the remote host.

The Bytes argument contains the size of the packet returned by the host.

The Elapsed argument contains the number of milliseconds that have elapsed since the packet was sent by the control.

Note The Reply event is only generated when the control is non-blocking, which is specified by setting the Blocking property to False.

See Also

Echo Event


Ping Timeout Event
Timeout Event

Description

The Timeout event is generated when a reply is not received from the remote host

Visual Basic

Sub control_Timeout ( [Index As Integer] )

Remarks

This event is generated when an ICMP echo datagram is not returned by the remote host within the amount of time specified by the Timeout property.

See Also

Timeout Property


 Image Viewer Control
Properties     Events

Description

The image viewer control enables an application to display graphic images.

File Name

CSIMGCTL.VBX, CSIMG16.OCX, CSIMG32.OCX

Object Type

Viewer

Remarks

The image viewer control can read and display graphics images in several formats, including BMP, GIF, PCX, JPEG, and XBM. The control maintains an internal cache of images to improve performance, and  images are shared between applications. For example, if three applications use the control to display a GIF image, only one copy of that image is loaded in memory.

Note The image viewer control is used by the Web browser control to display in-line graphics images.

Requirements

The image viewer control requires Microsoft Windows 3.1 or later and Visual Basic 3.0 or later. The OLE controls require Visual Basic 4.0 or another compatible container. It is recommended that the video adapter and display driver support 256 colors or higher.

Distribution

When you distribute your application that uses the image viewer control, you should install the appropriate file in the Windows system directory. For the 16-bit controls, the CSIMGL16.DLL file must be installed, and for the 32-bit control, the CSIMGL32.DLL file must be installed in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.
Portions developed by the Independent JPEG Group


Image Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

Align	hWnd	*ImageWidth	*Stretch
*AutoSize	*Image	Index	TabIndex
BackColor	*ImageColors	*IsTransparent	TabStop
BorderStyle	*ImageFile	Left	Tag
DragIcon	*ImageHeight	MousePointer	*Tiled
DragMode	*ImageLeft	Name	*TransColor
Enabled	*ImageTop	*Reload	Visible
Height	*ImageType	*ScrollBars	Width


Viewer AutoSize Property
AutoSize Property

Description

Automatically resize the control to the dimensions of the image

Visual Basic

[form.]control.AutoSize [ = { True | False } ]

Remarks

The AutoSize property determines if the image viewer is resized to the dimensions of the image. If set to True, the control is resized so that the entire image is displayed. If False, the image will be clipped to the dimensions of the control window.

Data Type

Integer (Boolean)

See Also

ScrollBars Property, Stretch Property, Tiled Property


Viewer Image Property
Image Property

Description

Return a handle to the device-independant bitmap

Visual Basic

[form.]control.Image

Remarks

The Image property returns a handle to the memory that was allocated for the image. This handle may be used with functions that manipulate device-independant bitmaps.

Note Because an image is shared between processes, any changes made to the image will be reflected in all processes that reference it. Since the handle to block of memory that contains the image may be invalidated at any time, do not store the return value in a variable. Instead, reference this property each time that you need the handle.

Data Type

Integer

See Also

ImageColors Property, ImageFile Property, ImageHeight Property, ImageLeft Property, ImageTop Property, ImageType Property, ImageWidth Property


Viewer ImageColors Property
ImageColors Property

Description

Returns the number of colors in the current image

Visual Basic

[form.]control.ImageColors

Remarks

The ImageColors property returns the number of colors used by the current image. If the returned value is 0, this indicates that the image is a 24-bit color image.

Data Type

Integer

See Also

Image Property, ImageFile Property, ImageHeight Property, ImageLeft Property, ImageTop Property, ImageType Property, ImageWidth Property


Viewer ImageFile Property
ImageFile Property

Description

Set or return the name of a graphics file to load

Visual Basic

[form.]control.ImageFile [ = filename$ ]

Remarks

The ImageFile property specifies the name of a graphics file to load. Currently, the control recognizes images in the following formats:

File Extension	Description
BMP	Windows bitmap
GIF	CompuServe GIF
JPG	JPEG
PCX	Paintbrush
XBM	X-Windows bitmap
If the same image file is referenced by multiple instances of the control, only one copy of the image is kept in memory.

Data Type

String

See Also

Image Property, ImageColors Property, ImageHeight Property, ImageLeft Property, ImageTop Property, ImageType Property, ImageWidth Property


Viewer ImageHeight Property
ImageHeight Property

Description

Returns the height of the current image

Visual Basic

[form.]control.ImageHeight

Remarks

The ImageHeight property returns the height of the current image in Twips. This property can be used to adjust the size of the control window when an image is loaded.

Data Type

Integer

See Also

Image Property, ImageColors Property,ImageFile Property, ImageLeft Property, ImageTop Property, ImageType Property, ImageWidth Property


Viewer ImageLeft Property
ImageLeft Property

Description

Set or return the distance between the internal left edge of the image and the left edge of the viewer window.

Visual Basic

[form.]control.ImageLeft [ =offset ]

Remarks

The ImageLeft property can be used to position the image within the viewer window. For example, in conjunction with the ImageTop property, it can be used to center an image within the viewer control.

Data Type

Integer

See Also

Image Property, ImageColors Property,ImageFile Property, ImageHeight Property, ImageTop Property, ImageType Property, ImageWidth Property


Viewer ImageTop Property
ImageTop Property

Description

Set or return the distance between the internal top edge of the image and the top edge of the viewer window.

Visual Basic

[form.]control.ImageTop [ =offset ]

Remarks

The ImageTop property can be used to position the image within the viewer window. For example, in conjunction with the ImageLeft property, it can be used to center an image within the viewer control.

Data Type

Integer

See Also

Image Property, ImageColors Property,ImageFile Property, ImageHeight Property, ImageLeft Property, ImageType Property, ImageWidth Property


Viewer ImageType Property
ImageType Property

Description

Return the type of image that is currently loaded

Visual Basic

[form.]control.ImageType

Remarks

The ImageType property returns an integer that identifies the type of image that is currently loaded by the control. The following image types are valid:

Value	Constant	Graphics Format
0	IMAGE_TYPE_NONE	None (No image loaded)
1	IMAGE_TYPE_BITMAP	Windows bitmap
2	IMAGE_TYPE_GIF	CompuServe GIF
3	IMAGE_TYPE_PCX	Paintbrush
4	IMAGE_TYPE_JPEG	JPEG
5	IMAGE_TYPE_XBM	X-Windows bitmap
Data Type

Integer

See Also

Image Property, ImageColors Property, ImageFile Property, ImageHeight Property, ImageLeft Property, ImageTop Property, ImageWidth Property


Viewer ImageWidth Property
ImageWidth Property

Description

Return the width of the current image

Visual Basic

[form.]control.ImageWidth

Remarks

The ImageWidth property returns the width of the current image in Twips. This property can be used to adjust the size of the control window when an image is loaded.

Data Type

Integer

See Also

Image Property, ImageColors Property,ImageFile Property, ImageHeight Property, ImageLeft Property, ImageTop Property, ImageType Property


Viewer IsTransparent Property
IsTransparent Property

Description

Determine if the image is transparent

Visual Basic

[form.]control.IsTransparent [ = { True | False }]

Remarks

This property returns True if the current image is transparent. A specific color, called the transparent color, is used to determine what pixels are transparent in the image. When an image file is loaded, this property is set to indicate if the image is transparent or not. GIF images may be transparent (depending on how the GIF was created), and XBM images are always transparent. By default, all other image types are not transparent.

Setting the IsTransparent property alters how the image is displayed. If set to True, the TransColor property is used to set the image transparent color. If set to False, the image will not longer be considered transparent, and will be displayed normally.

Data Type

Integer (Boolean)

See Also

TransColor Property


Viewer Reload Property
Reload Property

Description

Reload the current image from disk

Visual Basic

[form.]control.Reload = True

Remarks

Setting the Reload property to True causes the current image to be reloaded from it's disk file. This property should be used if some change was made to the file contents, and the application wishes to view the changes.

Note Reloading the image may cause previous values of the Image property to be invalidated. For this reason, you should never store the value of the Image property in a variable, but rather reference the property directly each time it is needed.

Data Type

Integer (Boolean)

See Also

Image Property


Viewer ScrollBars Property
ScrollBars Property

Description

Set the number of times the control attempts to resolve a hostname

Visual Basic

[form.]control.ScrollBars [ = which ]

Remarks

The ScrollBars property determines what kind of scroll bars are displayed if the image is larger than the viewer control's window. It may be one of the following values:

Value	Description
0	Do not display scrollbars
1	Display horizontal scrollbars for images wider than the control window
2	Display vertical scrollbars for images higher than the control window.
3	Display both horizontal and vertical scrollbars if necessary.
Data Type

Integer

See Also

AutoSize Property


Viewer Stretch Property
Stretch Property

Description

Enable or disable stretching the image to the size of the control window

Visual Basic

[form.]control.Stretch [ = { True | False } ]

Remarks

The Stretch property determines how the image is drawn in the control. If set to True, the image is stretched (or compressed) so that it fits within the boundries of the control window. By default the property is set to False, which causes the control to be drawn as is (with any part of the image outside of the window being clipped).

Data Type

Integer (Boolean)

See Also

AutoSize Property, Tiled Property


Viewer Tiled Property
Tiled Property

Description

Enable or disable tiling the image

Visual Basic

[form.]control.Tiled [ = { True | False } ]

Remarks

The Tiled property, if set to True, causes the current image to be tiled across the control window. The control paints the image, starting at the upper-left corner and proceeding to the right and down, until the control window is filled.

Data Type

Integer (Boolean)

See Also

AutoSize Property, Stretch Property


Viewer TransColor Property
TransColor Property

Description

Determines the image transparent color

Visual Basic

[form.]control.TransColor [ = color ]

Remarks

This property specifies the transparent color used by the image. For images that are not transparent, the default value of this property is 0 (black) and setting this property has no effect.

Visual Basic uses the Microsoft Windows environment RGB scheme for colors.  Each property has the following ranges of settings:

Range of settings	Description
Normal RGB colors	Colors specified by using the Color palette, or by using the RGB or QBColor functions in code.
System default colors	Colors specified with system color constants from CONSTANT.TXT, a Visual Basic file that specifies system defaults.  The Windows environment substitutes the user's choices as specified in the user's Control Panel settings.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF).  The high byte of a number in this range equals 0; the lower three bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively.  The red, green, and blue components are each represented by a number between 0 and 255 (&HFF).  If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel and enumerated in CONSTANT.TXT.

Data Type

Long (Color)

See Also

IsTransparent Property


Image Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Change	DragOver	LostFocus	*Paint
Click	KeyDown	MouseDown	*Resize
DblClick	KeyPress	MouseMove
DragDrop	KeyUp	MouseUp


 Network News Control
Properties     Methods     Events     Errors

Description

The NNTP client control enables an application to scan, retrieve and post articles on a remote news server.

File Name

CSNWSCTL.VBX, CSNWS16.OCX, CSNWS32.OCX

Object Type

NewsClient

Requirements

The NNTP control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the NNTP control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


NNTP Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*GroupTitle	*LastError	*RecvData	*SocketError
*Article	*Handle	*LastUpdate	*RecvLen	*State
*ArticleCount	*HostAddress	Left	*RecvNext	Tag
*AutoResolve	*HostName	*Library	*RemotePort	*Timeout
*Blocking	Index	*LocalAddress	*RemoteService	Top
*Command	*IsBlocked	*LocalName	*ResultCode	*UserName
*Connected	*IsClosed	*MessageId	*ResultString	*Vendor
*DateStamp	*IsReadable	*MultiLine	*SendData	*Version
*FirstArticle	*IsWritable	Name	*SendLen
*GroupName	*LastArticle	*Password	*Socket


NNTP Action Property
Action Property

Description

Setting this property causes the NNTP client to take some action, such as connecting to a remote server or retreiving an article.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	NNTP_ACTION_CONNECT	Connect to a NNTP server running on the system specified by the HostAddress or HostName properties.
2	NNTP_ACTION_DISCONNECT	Disconnect from the NNTP server, terminating the client session.
3	NNTP_ACTION_LISTGROUPS	Retrieve the list of active newsgroups available on the server.
4	NNTP_ACTION_NEWGROUPS	Retrieve the list of new newsgroups added to the server since the date specified by the LastUpdate property.
5	NNTP_ACTION_LISTARTICLES	Retrieve a list of articles, starting with the article specified by the FirstArticle property, and ending with the article specified by the LastArticle property.
6	NNTP_ACTION_GETHEADER	Return the header for the news article specified by the Article property.
7	NNTP_ACTION_GETARTICLE	Return the header and body of the news article specified by the Article property.
8	NNTP_ACTION_NEXTARTICLE	Return the next available news article.
9	NNTP_ACTION_PREVARTICLE	Return the previous news article
10	NNTP_ACTION_NEWARTICLE	Begin a new news article to be posted to the server.
11	NNTP_ACTION_POSTARTICLE	Post the article to the news server
12	NNTP_ACTION_AUTHENTICATE	Perform client authentication using the UserName and Password properties.
13	NNTP_ACTION_CANCEL	Cancel the current current action
Data Type

Integer

See Also

Blocking Property, Connected Property, State Property, Timeout Property


NNTP Article Property
Article Property

Description

Set or return the current article number

Visual Basic

[form.]control.Article [= articleno ]

Remarks

The Article property sets or returns the current news article number. Setting the Article property updates the MessageId property to reflect the specified article's message ID.

Data Type

Long

See Also

ArticleCount Property, FirstArticle Property, LastArticle Property, MessageId Property


NNTP ArticleCount Property
ArticleCount Property

Description

Return the number of available articles

Visual Basic

[form.]control.ArticleCount

Remarks

The ArticleCount property returns the number of articles that are available in the current newsgroup. Note that this is a read-only property available at run-time.

Data Type

Long

See Also

Article Property, FirstArticle Property, LastArticle Property


NNTP Command Property
Command Property

Description

Specify a command to execute on remote host

Visual Basic

[form.]control.Command [ = nntpcmd$ ]

Remarks

Setting the Command property causes the specified command to be executed on the server. This allows the application to take advantage of extended commands that are not directly available through the control. The ResultCode property should be checked to determine if the command was successful or not.

Note  If the command would result in multiple lines of output by the server, such as a listing of news articles, the MultiLine property must be set to True after the command is issued.

Data Type

String

See Also

MultiLine Property, ResultCode Property, ResultString Property


NNTP DateStamp Property
DateStamp Property

Description

Return the current date in the format used by the article header

Visual Basic

[form.]control.DateStamp

Remarks

The DateStamp property returns the current date and time in a format that is commonly used in article headers.

Data Type

String


NNTP FirstArticle Property
FirstArticle Property

Description

Return the first available article number

Visual Basic

[form.]control.FirstArticle

Remarks

The FirstArticle property returns the first article number available in the current newsgroup. Note that this is a read-only property available at run-time.

Data Type

Long

See Also

Article Property, ArticleCount Property, LastArticle Property


NNTP GroupName Property
GroupName Property

Description

Set or return the current newsgroup name

Visual Basic

[form.]control.GroupName[= grpname$ ]

Remarks

The GroupName property sets or returns the current newsgroup. Setting this property causes the related properties, such as FirstArticle and LastArticle, to be updated.

Data Type

String

See Also

GroupTitle Property


NNTP GroupTitle Property
GroupTitle Property

Description

Return a string describing the current newsgroup

Visual Basic

[form.]control.GroupTitle

Remarks

The GroupTitle property returns a string describing the current newsgroup. This property is read-only and  available only at run-time.

Data Type

String

See Also

GroupName Property


NNTP LastArticle Property
LastArticle Property

Description

Return the last available article number

Visual Basic

[form.]control.LastArticle

Remarks

The LastArticle property returns the last article number available in the current newsgroup. Note that this is a read-only property available at run-time.

Data Type

Long

See Also

Article Property, ArticleCount Property, FirstArticle Property


NNTP LastUpdate Property
LastUpdate Property

Description

Set or return the date used to return new newsgroups

Visual Basic

[form.]control.LastUpdate[= datestr$ ]

Remarks

The LastUpdate property determines the date and time from which new newsgroups are listed by the server. The format of the date must be as follows: YYMMDD HHMMSS

Data Type

String


NNTP MessageId Property
MessageId Property

Description

Set or return the current article by message ID

Visual Basic

[form.]control.MessageId [= msgid$ ]

Remarks

The MessageId property sets or returns the current message ID string. Each news article has a unique string which identifies that message. Setting the MessageId property causes the current article number to change to the given message. An error is generated if the property is set to an invalid message ID.

Data Type

String

See Also

Article Property, ArticleCount Property, FirstArticle Property, LastArticle Property


NNTP MultiLine Property
MultiLine Property

Description

Enable the processing of multiple lines of data from the server

Visual Basic

[form.]control.MultiLine [= { True |  False } ]

Remarks

The MultiLine property determines how the control processes data sent from the NNTP server. If False, the control will only process single lines of data. If set to True, the control will accept multiple lines of data, with the end of data delimited by a single period on an empty line.

Note  This property should only be set after the Command property is used to specify a command that returns multiple lines of output.

Data Type

Integer (Boolean)

See Also

Command Property


NNTP State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	NNTP_CLIENT_UNUSED	The control is not in use; no connection has been established with the remote server.
1	NNTP_CLIENT_IDLE	The control is connected to a remote server, but is not active.
2	NNTP_CLIENT_CONNECTING	The control is in the process of connecting to the remote host.
3	NNTP_CLIENT_GROUPLIST	The control is returning a list of newsgroups.
4	NNTP_CLIENT_ARTICLELIST	The control is returning a list of news article
5	NNTP_CLIENT_READING	The control is reading data sent by the the server; typically this state indicates that an article is being retrieved.
6	NNTP_CLIENT_POSTING	The controls is posting an article to the news server.
Data Type

Integer


NNTP Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Authenticate	*GetArticle	*NewArticle	*PreviousArticle
*Cancel	*GetHeader	*NewGroups	*Read
*Connect	*ListArticles	*NextArticle	*Write
*Disconnect	*ListGroups	*PostArticle
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


NNTP Authenticate Method
Authenticate Method

Description

Authenticate the news client

Visual Basic

[form.]control.Authenticate username$, password$

Remarks

This method identifies the client to the remote server. If the user name or password is invalid, an error will occur. This method should only be used if the server indicates that authentication is required by returning an eror

The username argument specifies the name of the user to login as.

The password argument specifies the password that authenticates the specified user. Note that the password is passed as clear text to the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Logout Method


NNTP GetArticle Method
GetArticle Method

Description

Return the header and body for the specified article

Visual Basic

[form.]control.GetArticle article%

Remarks

This method requests that the server return the header and body of the specified article. The data can be retrieved through the RecvData property or Read method. This method updates the Article property.

The article argument specifies the news article number.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, GetHeader Method


NNTP GetHeader Method
GetHeader Method

Description

Return the header for the specified article

Visual Basic

[form.]control.GetHeader article%

Remarks

This method requests that the server return the header of the specified article. The data can be retrieved through the RecvData property or Read method. This method updates the Article property.

The article argument specifies the news article number.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, GetArticle Method


NNTP ListArticles Method
ListArticles Method

Description

Return a list of articles in the specified range

Visual Basic

[form.]control.ListArticles firstarticle%, lastarticle%

Remarks

This method requests that the server return a list of news articles in the specified range. The NewsArticle event will be fired for each article returned by the server. The FirstArticle and LastArticle properties are updated by this method.

The firstarticle argument specifies the first article to return

The lastarticle argument specifies the last article to return. This value must be greater than the first article number.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, NewsArticle Event


NNTP ListGroups Method
ListGroups Method

Description

Return a list of newsgroups available on the server

Visual Basic

[form.]control.ListGroups

Remarks

This method requests that the server return a list of available news groups. The NewsGroup event will be fired for each group returned by the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, NewGroups Method, NewsGroup Event


NNTP NewArticle Method
NewArticle Method

Description

Create a new article to be posted to the server

Visual Basic

[form.]control.NewArticle

Remarks

The NewArticle method is used to create a new article that is to be posted to the server. Upon the successful completion of this method, the article header and body should be sent to the server using the SendData property or Write method. Once the entire article has been sent, the PostArticle method should be used to complete the process.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, PostArticle Method


NNTP NewGroups Method
NewGroups Method

Description

Return a list of new newsgroups available on the server

Visual Basic

[form.]control.NewGroups datestr$

Remarks

This method requests that the server return a list of  newsgroups that have been added since the specified date. The NewsGroup event will be fired for each group returned by the server.

The datestr argument specifies the date after which the groups were created. The format of the string must follow the same as that of the LastUpdate property.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, LastUpdate Property, ListGroups Method, NewsGroup Event


NNTP NextArticle Method
NextArticle Method

Description

Return the next article in the current newsgroup

Visual Basic

[form.]control.NextArticle

Remarks

This method requests that the server return the next article in the newsgroup.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, PreviousArticle Method


NNTP PostArticle Method
PostArticle Method

Description

Post the current article to the newsgroup

Visual Basic

[form.]control.PostArticle

Remarks

The PostArticle method is the last step in posting an article, after the header and body of the message have been written to the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, NewArticle Method


NNTP PreviousArticle Method
PreviousArticle Method

Description

Return the previous article in the current newsgroup

Visual Basic

[form.]control.PreviousArticle

Remarks

This method requests that the server return the previous article in the newsgroup.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, NextArticle Method


NNTP Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*Disconnect	*LastError	*NewsArticle	*Read
*Connect	*LastArticle	*LastGroup	*NewsGroup


NNTP Cancel Event
Cancel Event

Description

The Cancel event is generated when a blocking operation is canceled

Visual Basic

Sub Socket_Cancel ([Index As Integer])

Remarks

This event is generated when a blocking operation, such as receiving a list of newsgroups, is canceled with the NNTP_ACTION_CANCEL action.

See Also

State Property, LastError Event


NNTP LastArticle Event
LastArticle Event

Description

Fired when the last news article was returned

Visual Basic

Sub control_LastArticle ( [Index As Integer] )

Remarks

The LastArticle event is fired when the last article has been returned by the server.

See Also

Action Property, LastGroup Event


NNTP LastGroup Event
LastGroup Event

Description

Fired when the last news group was returned

Visual Basic

Sub control_LastGroup ( [Index As Integer] )

Remarks

The LastGroup event is fired when the last newsgroup has been returned by the server.

See Also

Action Property, LastArticle Event


NNTP NewsArticle Event
NewsArticle Event

Description

Fired when information about an article is returned by the server

Visual Basic

Sub control_NewsArticle ( [Index As Integer,] Article As Long, Subject As String, Author As String, Posted As String, MessageId As String, References As String, ByteCount As Long, LineCount As Long )

Remarks

The LastArticle event is fired when the last article has been returned by the server.

See Also

Action Property, NewsGroup Event


NNTP NewsGroup Event
NewsGroup Event

Description

Fired when information about a news group is returned by the server

Visual Basic

Sub control_NewsGroup ( [Index As Integer,] GroupName As String, FirstArticle As Long, LastArticle As Long, Posting As Integer )

Remarks

The LastArticle event is fired when the last article has been returned by the server.

See Also

Action Property, LastGroup Event


NNTP Control Errors
 Value                   Description

    22301                   Invalid handle to NNTP client
    22302                   Invalid parameter passed to function
    22303                   Cannot initialize socket library
    22304                   Cannot allocate memory
    22305                   Cannot resolve hostname
    22306                   Cannot create socket
    22307                   Cannot connect to remote server
    22308                   Cannot select socket
    22309                   Timeout waiting for response from server
    22310                   Invalid response from server
    22311                   Cannot read from socket
    22312                   Cannot write to socket
    22313                   Server connection closed
    22314                   Client operation in progress
    22315                   Client operation aborted
    22316                   News service discontinued
    22317                   Unknown newsgroup
    22318                   No newsgroup selected
    22319                   No article selected
    22320                   Last article in newsgroup
    22321                   First article in newsgroup
    22322                   Invalid article number
    22323                   Cannot transfer article
    22324                   Article transfer failed
    22325                   Article rejected
    22326                   Posting not allowed
    22327                   Post failed
    22328                   Command not recognized
    22329                   Access restricted
    22330                   Program fault, command not performed
    22331                   User authentication required
    22332                   User authentication failed
    22333                   Authentication type not supported
    22334                   User authentication not required


POP Control
 Post Office Protocol Control
Properties      Methods       Events      Errors

Description

The POP3 client control enables an application to scan and retrieve mail messages stored on a remote host.

File Name

CSPOPCTL.VBX, CSPOP16.OCX, CSPOP32.OCX

Object Type

PopClient

Requirements

The POP3 control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the POP3 control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


POP Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	Index	*LocalName	*RecvNext	Top
*AutoResolve	*IsBlocked	*Message	*RemotePort	*Timeout
*Binary	*IsClosed	*MessageCount	*RemoteService	*UserName
*Blocking	*IsReadable	*MessageSize	*ResultCode	*Vendor
*Command	*LastError	*MultiLine	*ResultString	*Version
*Connected	Left	Name	*Socket
*Handle	*Library	*Password	*SocketError
*HostAddress	*LineBreak	*RecvData	*State
*HostName	*LocalAddress	*RecvLen	Tag


POP Action Property
Action Property

Description

Setting this property causes the POP client to take some action, such as connecting to a remote server or retrieving a message.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	POP_ACTION_CONNECT	Connect to a POP3 server running on the system specified by the HostAddress or HostName properties.
2	POP_ACTION_DISCONNECT	Disconnect from the POP3 server, closing the current user's mailbox.
3	POP_ACTION_GETHDR	Retrieve the header for the specified message, but not the body of the message itself.
4	POP_ACTION_GETMSG	Retrieve the complete message, header and body, from the POP3 server.
5	POP_ACTION_DELMSG	Delete the message from the mailbox on the remote system.
6	POP_ACTION_RESET	Reset the control and undelete any messages that are marked for deletion.
7	POP_ACTION_CANCEL	Cancel the current blocking operation. After the operation is canceled, the application should disconnect from the remote server.
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Connected Property, State Property, Timeout Property


POP Binary Property
Binary Property

Description

Enable or disable reading binary data from the server

Visual Basic

[form.]control.Binary [= { True | False }]

Remarks

The Binary property specifies how binary data is handled by the control. If set to True, any binary data is read by the client unmodified. The default property value is False, which causes the control to ignore any non-text characters received.

Note This property should only be enabled when retrieving messages created with an alternate (foreign language) character set that uses the eighth bit.

Data Type

Integer (Boolean)

See Also

LineBreak Property


POP LineBreak Property
LineBreak Property

Description

Enable or disable line breaks in data read from the server

Visual Basic

[form.]control.LineBreak [= { True | False }]

Remarks

The LineBreak property controls how data is read from the server. If set to True, the control will return one of text at a time. If set to False, the control will read as much data as possible, regardless if the end-of-line is reached or not. The end-of-line is marked by a carriage return-linefeed pair.

Data Type

Integer (Boolean)

See Also

Binary Property


POP Message Property
Message Property

Description

Set or return the current message number

Visual Basic

[form.]control.Message [= msgno ]

Remarks

The Message property sets or returns the current message number. Message numbers range from 1 through the number of messages available on the server, as returned by the MessageCount property. Setting the Message property to an invalid message number will generate an error.

Data Type

Integer

See Also

MessageCount Property, MessageSize Property


POP MessageCount Property
MessageCount Property

Description

Return the number of messages available on the server

Visual Basic

[form.]control.MessageCount

Remarks

The MessageCount property returns the number of messages available to be retrieved for the current user.

Data Type

Integer

See Also

Message Property, MessageSize Property


POP MessageSize Property
MessageSize Property

Description

Return the size of the current message in bytes

Visual Basic

[form.]control.MessageSize

Remarks

The MessageSize property returns the size of the current message in bytes. The size includes the header and body portion of the message.

Data Type

Integer

See Also

Message Property, MessageCount Property


POP State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	POP_CLIENT_UNUSED	No connection established
1	POP_CLIENT_IDLE	Client connection is not active
2	POP_CLIENT_CONNECTING	Establishing connection with server
3	POP_CLIENT_LOGIN	Logging user into server
4	POP_CLIENT_TRANSFER	Data transfer in progress
Data Type

Integer

See Also

IsBlocked Property


POP Command Property
Command Property

Description

Specify a command to execute on remote host

Visual Basic

[form.]control.Command [ = popcmd$ ]

Remarks

Setting the Command property causes the specified command to be executed on the server. This allows the application to take advantage of extended commands that are not directly available through the control. The ResultCode property should be checked to determine if the command was successful or not.

Note  If the command would result in multiple lines of output by the server, such as a mail message, the MultiLine property must be set to True after the command is issued.

Data Type

String

See Also

MultiLine Property, ResultCode Property, ResultString Property


POP MultiLine Property
MultiLine Property

Description

Enable the processing of multiple lines of data from the server

Visual Basic

[form.]control.MultiLine [= { True |  False } ]

Remarks

The MultiLine property determines how the control processes data sent from the POP server. If False, the control will only process single lines of data. If set to True, the control will accept multiple lines of data, with the end of data delimited by a single period on an empty line.

Note  This property should only be set after the Command property is used to specify a command that returns multiple lines of output.

Data Type

Integer (Boolean)

See Also

Command Property


POP Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*DeleteMessage	*GetHeader	*Read
*Connect	*Disconnect	*GetMessage
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


POP DeleteMessage Method
DeleteMessage Method

Description

Delete the specified message from the mailbox

Visual Basic

[form.]control.DeleteMessage mesgid%

Remarks

The mesgid argument specifies the message number

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

GetHeader Method, GetMessage Method


POP GetHeader Method
GetHeader Method

Description

Return the header for the specified message

Visual Basic

[form.]control.GetHeader mesgid%

Remarks

This method requests that the server return the header of the specified message. The data can be retrieved through the RecvData property or Read method.

The mesgid argument specifies the message number.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

GetMessage Method


POP GetMessage Method
GetMessage Method

Description

Return the message header and body for the specified message

Visual Basic

[form.]control.GetMessage mesgid%

Remarks

This method requests that the server return the header and body of the specified message. The data can be retrieved through the RecvData property or Read method.

The mesgid argument specifies the message number.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

GetHeader Method


POP Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*Disconnect	*LastError	*Read


POP Control Errors
  Value                   Description

    22301                   Invalid handle to POP client
    22302                   Invalid parameter passed to function
    22303                   Cannot initialize socket library
    22304                   Cannot allocate memory
    22305                   Cannot resolve hostname
    22306                   Cannot create socket
    22307                   Cannot connect to remote server
    22308                   Cannot select socket
    22309                   Timeout waiting for response from server
    22310                   Invalid response from server
    22311                   Cannot read from socket
    22312                   Cannot write to socket
    22313                   Cannot login to remote server
    22314                   Client not logged into server
    22315                   Invalid message identifier
    22316                   Remote server connection closed
    22317                   Remote server is busy


 Remote Access Service Control
Properties      Methods      Events

Description

The Remote Access Service (RAS) control enables the developer to establish a dial-up network connection with a remote server.

File Name

CSRASCTL.VBX, CSRAS16.OCX, CSRAS32.OCX

Object Type

Dialer

Remarks

This control provides a way for client applications to connect to a remote server using the Microsoft Windows Remote Access Service (RAS). To use this control, the RAS software must be installed on the local system. For dial-up access to the Internet, the TCP/IP protocol must be installed and configured. Refer to your system documentation for information about installing and configuring RAS on your system.

For those applications which may be used in a mobile environment, or otherwise require remote network access, the RAS control provides a convenient interface to this service. Connections can be established and discontinued under the direct control of the program, rather than requiring that the user execute another command before running your application.

Note It is safe to include the control in an application, even if remote access is not installed or configured on the local system.

Requirements

The RAS control requires Microsoft Windows for Workgroups 3.11, Windows 95, or  Windows NT 3.51 and Visual Basic 3.0 or later. For dial-up access to the Internet, the TCP/IP protocol must be installed and configured.

Distribution

When you distribute your application that uses the RAS control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


RAS Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*Connected	*Interval	*PhoneBookEntries	*Timeout
*AutoUpdate	*DeviceName	Name	*PhoneEntry	Top
*Available	*DeviceType	*Password	*PhoneNumber	*UserDomain
*Callback	*DialogState	*PhoneBook	*State	*UserName
*CallbackNumber	Index	*PhoneBookEntry	Tag


RAS Action Property
Action Property

Description

Setting this property causes the control to take some action, such as establishing a connection with a remote server.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	RAS_ACTION_CONNECT	Establish a dial-up network connection with the specified server.
2	RAS_ACTION_DISCONNECT	Disconnect from a dial-up network server, or cancel a connection attempt that is in progress.
3	RAS_ACTION_RESET	Reset the control state, disconnecting from the remote server
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Connected Property, Connect Event, Disconnect Event


RAS Available Property
Available Property

Description

Determine if the Remote Access Service is available

Visual Basic

[form.]control.Available

Remarks

This read-only property returns True if the Remote Access Service (RAS) software has been installed on the system. Note that this property does not indicate that the required hardware is available or that a specific protocol has been configured.

Data Type

Integer (Boolean)


RAS Callback Property
Callback Property

Description

Specifies that the remote server should call the system back

Visual Basic

[form.]control.Callback [ = { True | False } ]

Remarks

Setting the Callback property specifies that the server should call the user back at telephone number specified by the CallbackNumber property. This property is ignored unless the user has "Set By Caller" callback permission on the server.

Data Type

Integer (Boolean)

See Also

CallbackNumber Property, PhoneEntry Property, PhoneNumber Property


RAS CallbackNumber Property
CallbackNumber Property

Description

Specifies the telephone number for the remote server to call back on

Visual Basic

[form.]control.CallbackNumber [ = number$ ]

Remarks

Setting the CallbackNumber property specifies that the server should call the user back at the given telephone number. This property is ignored unless the user has "Set By Caller" callback permission on the server. Assigning an asterisk to this property causes the number stored in the phone book entry to be used for callback.

Data Type

String

See Also

Callback Property, PhoneEntry Property, PhoneNumber Property


RAS DeviceName Property
DeviceName Property

Description

Return the name of the device the connection was established with

Visual Basic

[form.]control.DeviceName

Remarks

The DeviceName property returns a description of the device that the connection was established on. For example, the string "US Robotics Sportster 28000" may be returned for a modem.

Data Type

String

See Also

DeviceType Property


RAS DeviceType Property
DeviceType Property

Description

Return the type of the device the connection was established with

Visual Basic

[form.]control.DeviceType

Remarks

The DeviceType property returns the type of device that the connection was established with. Possible values are "modem", "pad", "switch", "isdn" or "null".

Data Type

String

See Also

DeviceName Property


RAS Password Property
Password Property

Description

The password required to establish a connection with the remote server

Visual Basic

[form.]control.Password [= password $]

Remarks

The Password property specifies the password required to establish a connection with the remote host. Note that this may not be the same password that is used to login to the server using terminal emulation software.

Data Type

String

See Also

UserName Property, UserDomain Property


RAS PhoneBook Property
PhoneBook Property

Description

Sets the file name of the Remote Access phone book to use

Visual Basic

[form.]control.PhoneBook [= pbfile$]

Remarks

The PhoneBook property specifies the file name of the Remote Access phone book. Setting this property to an empty string causes the default phone book to be used.

Data Type

String

See Also

PhoneBookEntry Property, PhoneBookEntries Property


RAS PhoneBookEntry Property
PhoneBookEntry Property

Description

Return the name for the specified phone book entry

Visual Basic

[form.]control.PhoneBookEntry(Index)

Remarks

The PhoneBookEntry property array contains a list of the entries in the current phone book, and may be used to establish a connection with a remote server. Specifying an index greater than the number of available entries in the phone book will generate an error.

Data Type

String

See Also

PhoneBookEntries Property, PhoneEntry Property


RAS PhoneBookEntries Property
PhoneBookEntries Property

Description

Return the number of entries in the current phone book

Visual Basic

[form.]control.PhoneBookEntries

Remarks

The PhoneBookEntries property returns the number of entries in the current phone book. A value of zero indicates that no phone book entries are available.

Data Type

Integer

See Also

PhoneBookEntry Property, PhoneEntry Property


RAS PhoneEntry Property
PhoneEntry Property

Description

Specify the phone book entry to use to establish a connection with a remote server

Visual Basic

[form.]control.PhoneEntry [ = entry$ ]

Remarks

The PhoneEntry property can be used to specify a phone book entry to use to connect with a remote server. The entry name identifies a communications profile which includes the telephone number, callback number and domain name of the remote host. Setting the PhoneEntry property to an empty string indicates that a telephone number will be provided to establish the connection.

Data Type

String

See Also

PhoneBookEntry Property, PhoneBookEntries Property, PhoneNumber Property


RAS PhoneNumber Property
PhoneNumber Property

Description

Specifies the telephone number of the remote server

Visual Basic

[form.]control.PhoneNumber [ = number$ ]

Remarks

The PhoneNumber property specifies the telephone number of the remote server. If this property is not set, then the PhoneEntry property must be set to a valid phone book entry. If both the PhoneNumber and PhoneEntry properties are defined, the PhoneNumber property will override the value specified in the phone book.

Data Type

String

See Also

PhoneEntry Property, CallbackNumber Property


RAS State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. It may be one of the following values:

Value	Constant	Description
-1	RAS_UNUSED	No connection has been established
0	RAS_OPENPORT	The communications port is about to be opened
1	RAS_PORTOPENED	The communications port has been opened
2	RAS_CONNECTDEV	A device is about to be connected.
3	RAS_DEVCONNECTED	A device has been connected successfully
4	RAS_ALLDEVCONNECTED	All devices in the device chain have been connected. At this point, the physical link is established.
5	RAS_AUTHENTICATE	The user authentication process is starting
14	RAS_AUTHENTICATED	The user has been authenticated
15	RAS_PREPCALLBACK	The line is about to be disconnected in preparation for callback
16	RAS_MODEMRESET	The modem is resetting itself in preparation for callback
17	RAS_WAITFORCALL	Waiting for callback from remote server
4096	RAS_PAUSED	Dialer paused for interactive login
4097	RAS_RETRYAUTH	Retrying user authentication
4098	RAS_CALLBACK	Callback has been set by caller
4099	RAS_PASSEXPIRED	Password has expired
8192	RAS_CONNECTED	The connection has been established
8193	RAS_DISCONNECTED	The connection has been terminated
The following additional values may be returned by the 32-bit control under Windows 95 or Windows NT:

Value	Constant	Description
19	RAS_STARTAUTH	User authentication started
20	RAS_CALLBACKDONE	The callback has completed
21	RAS_NETLOGON	Logging on network

Data Type

Integer

See Also

Status Event


RAS UserName Property
UserName Property

Description

Set the user name that is required to establish a connection with the remote server

Visual Basic

[form.]control.UserName [= name$]

Remarks

The UserName property specifies the user that is logging in to the remote server, and is required for authentication purposes.

Data Type

String

See Also

Password Property, UserDomain Property


RAS UserDomain Property
UserDomain Property

Description

Specifies the NT domain on which user authentication is to occur.

Visual Basic

[form.]control.UserDomain [= name$]

Remarks

The UserDomain property is used to specify the NT domain on which  the user name and password will be authenticated. An empty string specifies the domain in which the Remote Access server is a member. An asterisk specifies the domain stored in the phone book entry.

Data Type

String

See Also

Password Property, UserName Property


RAS AutoUpdate Property
AutoUpdate Property

Description

Automatically update properties when phonebook entry is selected

Visual Basic

[form.]control.AutoUpdate = { True | False }

Remarks

This property determines if the UserName, Password and UserDomain properties are automatically updated when the PhoneEntry property is set. By default this property value is False, which means that those properties must be explicitly set by the application.

Note  This property may only be enabled on 32-bit platforms (Windows 95 or Windows NT). Attempting to set this property in a 16-bit application will result in an error.

Data Type

Integer (Boolean)

See Also

Password Property, UserDomain Property, UserName Property


RAS Interval Property
Interval Property

Description

Set or return the interval at which the connection is monitored

Visual Basic

[form.]Socket.Interval [= milliseconds]

Remarks

This property specifies the interval, in milliseconds, at which the connection is monitored by the control. The minimum value of 0 indicates that the control should not monitor the connection.The maximum interval value is 65536 milliseconds, which is slightly more than one minute. The default value is 1000, which causes the control to check the connection status every second.

Note Setting the property value to 0 will prevent the control from detecting certain conditions, such as a disconnected telephone line or a modem that is turned off.

Data Type

Long

See Also

Status Event, Timeout Event, Timeout Property


RAS Timeout Property
Timeout Property

Description

Set or return the number of seconds until a connection attempt fails

Visual Basic

[form.]Socket.Timeout [= seconds]

Remarks

This property specifies the number of seconds that the control has to establish a connection with a remote server. If a connection is not established within that time period, the Timeout event is fired and the control is reset. The default value for this property is 60 seconds. A value of 0 indicates that the control should wait indefinately for a connection attempt to succeed.

Data Type

Short

See Also

Interval Property, Status Event, Timeout Event


RAS DialogState Property
DialogState Property

Description

Set or return the state of the connection dialog

Visual Basic

[form.]Socket.DialogState [= dlgstate%]

Remarks

This property determines the state of the connection dialog that is displayed under Windows 95. The following values may be used:

Constant	Description
0	The dialog is shown in it's normal state
1	The dialog is minimized to an icon. If this property is set prior to establishing a connection, the dialog is minimized after the connection is established.
2	The dialog is hidden. If this property is set prior to establishing a connection, the dialog is hidden after the connection is established.
Note If the property value is set to automatically minimize or hide the dialog, the control depends on an internal timer to set the window state. This means that the Interval property must be set to a non-zero value, with a recommended value set at 1000 milliseconds or greater.

Data Type

Integer

See Also

Interval Property


RAS Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*DeleteEntry	*EditEntry	*Reset
*CreateEntry	*Disconnect	*RenameEntry	*UpdateEntry
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


RAS CreateEntry Method
CreateEntry Method

Description

Create a new phonebook entry on the local system

Visual Basic

[form.]control.CreateEntry

Remarks

The CreateEntry method displays a dialog box which allows the user to create a new phonebook entry on the system.

Note This method may only be used in a 32-bit application, and may not be supported under all versions of Windows 95 or Windows NT. Attempting to use this method with the 16-bit OLE control will result in an error.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

DeleteEntry Method, EditEntry Method, RenameEntry Method, UpdateEntry Method


RAS DeleteEntry Method
DeleteEntry Method

Description

Delete a phonebook entry from the local system

Visual Basic

[form.]control.DeleteEntry entryname$

Remarks

The DeleteEntry method deletes the specified entry from the local phonebook.

Note This method may only be used in a 32-bit application, and may not be supported under all versions of Windows 95 or Windows NT. Attempting to use this method with the 16-bit OLE control will result in an error.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

CreateEntry Method, EditEntry Method, RenameEntry Method, UpdateEntry Method


RAS EditEntry Method
EditEntry Method

Description

Edit an existing phonebook entry on the local system

Visual Basic

[form.]control.EditEntry entryname$

Remarks

The EditEntry method edits the specified entry from the local phonebook. This will cause a dialog box to be displayed from which the user can change the connection information.

Note This method may only be used in a 32-bit application, and may not be supported under all versions of Windows 95 or Windows NT. Attempting to use this method with the 16-bit OLE control will result in an error.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

CreateEntry Method, DeleteEntry Method, RenameEntry Method, UpdateEntry Method


RAS RenameEntry Method
RenameEntry Method

Description

Rename an existing phonebook entry

Visual Basic

[form.]control.RenameEntry oldname$, newname$

Remarks

The RenameEntry method renames  the specified entry in the local phonebook. The new entry name must not already exist in the phonebook.

Note This method may only be used in a 32-bit application, and may not be supported under all versions of Windows 95 or Windows NT. Attempting to use this method with the 16-bit OLE control will result in an error.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

CreateEntry Method, DeleteEntry Method, EditEntry Method, UpdateEntry Method


RAS Reset Method
Reset Method

Description

Resets the control state and disconnects the current session

Visual Basic

[form.]control.Reset

Remarks

The Reset method resets the control's internal state, and disconnects the active session if one was established.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


RAS UpdateEntry Method
UpdateEntry Method

Description

Update the current phonebook entry

Visual Basic

[form.]control.UpdateEntry

Remarks

The UpdateEntry method causes the current phonebook entry to be updated with the values of the UserName, Password and UserDomain properties.

Note This method may only be used in a 32-bit application, and may not be supported under all versions of Windows 95 or Windows NT. Attempting to use this method with the 16-bit OLE control will result in an error.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

CreateEntry Method, DeleteEntry Method, EditEntry Method, RenameEntry Method


RAS Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*Disconnect	*LastError	*Status	*Timeout


RAS Status Event
Status Event

Description

The Status event is generated when the RAS client state changes

Visual Basic

Sub control_Status ([Index As Integer,] State As Integer)

Remarks

This event is generated when the status of the Remote Access client changes.

The State argument specifies the state of the client when the event is generated. This is the same value as returned by the State property.

See Also

State Property


RAS Timeout Event
Timeout Event

Description

The Timeout event is generated when the control is unable to establish a connection

Visual Basic

Sub control_Timeout ([Index As Integer])

Remarks

This event is generated when the control is unable to establish a connection with a remote server in the number of seconds specified by the Timeout property.

See Also

Timeout Property


Remote Command Control
 Remote Command Execution Control
Properties       Methods       Events        Errors

Description

The remote execution client control allows an application to execute a command on a UNIX server, with the input and output of the command redirected through the connection.

File Name

CSREXCTL.VBX, CSREX16.OCX, CSREX32.OCX

Object Type

RemoteCmd

Requirements

The remote execution control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the remote command control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


RCMD Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*IsBlocked	*LocalName	*RemoteService	*Timeout
*AutoResolve	*IsClosed	Name	*SendData	*UserName
*Blocking	*IsReadable	*Password	*SendLen	*Vendor
*Command	*IsWritable	*RecvData	*Socket	*Version
*Connected	*LastError	*RecvLen	*SocketError
*HostAddress	*Library	*RecvNext	*State
*HostName	*LocalAddress	*RemotePort	*Terminal


RCMD Action Property
Action Property

Description

Setting this property causes the control to take some action, such as executing a command on the remote host.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	RCMD_ACTION_LOGIN	Login to a remote host as the user specified in the UserName property.
2	RCMD_ACTION_EXECUTE	Execute the specified command on the remote host. This action requires that both a username and password be provided by the client.
3	RCMD_ACTION_COMMAND	Execute the specified command on the remote host without requiring a password.
4	RCMD_ACTION_DISCONNECT	Close the socket connection with the remote host. This will logout the current user and/or terminate any command that is executing.
Only the RCMD_ACTION_EXECUTE action requires that the Password property to be set by the client application. The other actions depend on what is called "host equivalence". This means that the remote host considers the client to be equivalent to itself, and as long as the specified user exists on the remote host, that user is permitted to login or execute commands on behalf of the user without requiring a password.

If configured improperly, host equivalence can introduce a significant security loophole. Refer to your UNIX system documentation for more information about host equivalence and the use of the various remote commands.

Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Command Property, Connected Property, State Property, TermType Property,Timeout Property, UserName Property


RCMD Command Property
Command Property

Description

Set or return the command to be executed on the remote host

Visual Basic

[form.]control.Command [= command$ ]

Remarks

The Command property specifies the command to be executed on the remote host. An error will be returned if the command is invalid on the remote system.

Data Type

String

See Also

Action Property


RCMD State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	RCMD_CLIENT_UNUSED	No connection established
1	RCMD_CLIENT_IDLE	Client connection is not active
2	RCMD_CLIENT_CONNECTING	Establishing connection with server
3	RCMD_CLIENT_RECEIVING	Client receiving data from server
4	RCMD_CLIENT_SENDING	Client sending data to server
5	RCMD_CLIENT_CLOSING	Client closing connection
Data Type

Integer

See Also

IsBlocked Property


RCMD Terminal Property
Terminal Property

Description

Set or return the terminal type used by the control

Visual Basic

[form.]control.Terminal [= termtype$ ]

Remarks

The Terminal property specifies the terminal type of the remote host for display purposes. When used in conjunction with the terminal emulation control, this property should be set to "ansi" or an equivalent terminal type.

Data Type

String

See Also

UserName Property


RCMD Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Disconnect	*Login	*Write
*Execute	*Read
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


RCMD Execute Method
Execute Method

Description

Execute the specified command on the remote host

Visual Basic

[form.]control.Execute hostname$, username$, password$, command$

Remarks

The Execute method executes the specified command on a remote host. Output from the command may be read using the RecvData property or Read method. Input can be supplied to the program using either the SendData property or the Write method.

The hostname argument specifies the name of the remote host to connect to. Either an IP address or host name may be specified.

The username argument specifies the name of the user on who's behalf the program will be executed. An error will occur if the user name is invalid. Note that on many systems, the user name is case-sensitive.

The password argument specifies the password used to authenticate the given use. An invalid password will generate an error.

The command argument specifies the command to execute on the remote system. The application may interact with the program by reading and writing through the control. The connection will be closed when the command terminates.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Login Method


RCMD Login Method
Login Method

Description

Login to the remote server

Visual Basic

[form.]control.Login hostname$, username$

Remarks

The Login method logs the specified user in on the remote host. Note that no password is provided to the remote host. This is because the remote login service uses user equivalence. If the client system is recognized by the remote host as being equivalent, the login will proceed directly. If the client system is not recognized, the server will prompt the user for a password. For more information about user equivlance and the remote login service, refer to your server's operating system documentation.

The hostname argument specifies the name of the remote host to connect to. Either an IP address or host name may be specified.

The username argument specifies the name of the user to login as. If the specified user does not exist, or the client system is not considered an equivalent host, a password prompt will be issued by the server.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Execute Method


RCMD Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*LastError	*Write
*Disconnect	*Read


SMTP Control
 Simple Mail Transfer Protocol Control
Properties     Methods     Events      Errors

Description

The SMTP client control enables an application to send electronic mail to a remote host.

File Name

CSMTPCTL.VBX, CSMTP16.OCX, CSMTP32.OCX

Object Type

SmtpClient

Requirements

The SMTP control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the SMTP control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


SMTP Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*HostAddress	*Library	*ResultString	*Timeout
*Address	*HostName	*LocalAddress	*SendData	*Vendor
*AutoResolve	Index	*LocalName	*SendLen	*Version
*Blocking	*IsBlocked	Name	*Socket
*Connected	*IsClosed	*Recipient	*SocketError
*DateStamp	*IsWritable	*RemotePort	*State
*Domain	*LastError	*RemoteService	Tag
*Handle	Left	*ResultCode	Top


SMTP Action Property
Action Property

Description

Setting this property causes the SMTP client to take some action, such as connecting to a server or sending a message.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	SMTP_ACTION_CONNECT	Connect to the remote SMTP server specified by the HostAddress or HostName properties.
2	SMTP_ACTION_DISCONNECT	Disconnect from the remote server.
3	SMTP_ACTION_ADDRESS	Begin the mail transaction. After a connection is established, this is the next action that must be taken before the message can be delivered.
4	SMTP_ACTION_SENDMAIL	End the mail transaction and deliver the message.
5	SMTP_ACTION_EXPAND	Expand the mail address specified in the Recipient property. This action cannot be used while a message is being composed.
6	SMTP_ACTION_VERIFY	Verify that the mail address specified in the Recipient property is a valid address. This action cannot be used while a message is being composed.
7	SMTP_ACTION_RESET	Reset the client and cancel the current mail transaction.
8	SMT_ACTION_CANCEL	Cancel the current blocking operation and return to the application.
The SMTP client control requires that certain actions be performed in sequence to deliver one or more messages. The steps are as follows:

1. Establish a connection using the SMTP_ACTION_CONNECT property. Once the connection has been established, the mail transaction may begin.

2. Begin the mail transaction by using the SMTP_ACTION_ADDRESS action. This action causes the control to send the mail address of the sender, as specified by the Address property, to the server.

3. Specify the mail address of the recipients by setting the Recipient property. Each time that the property is set, that recipient is added to the list of those who will receive the message.

4. After all recipients have been specified, send the message to the server using the SendData property. Note that the header must be separated from the body of the message by a blank line.

5. Once the message has been sent to the server, the SMTP_ACTION_SENDMAIL action should be used, which will instruct the server to deliver the message.

6. If additional messages are to be sent, the SMTP_ACTION_RESET action should be used, followed by SMTP_ACTION_ADDRESS to begin another  transaction.

The ResultCode property should be checked after each action to check the code returned by the server. If an error is indicated, the user should be notified and the current transaction canceled by using the SMTP_ACTION_RESET action.

Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Address Property, Blocking Property, Connected Property, Recipient Property, ResultCode Property, State Property, Timeout Property


SMTP Address Property
Address Property

Description

Set or return the mail address of the sender

Visual Basic

[form.]control.Address [= address$]

Remarks

The Address property specifies the e-mail address of the message sender. Typically this is the same address that is specified in the "From" and/or "Reply To" fields in the message header.

Data Type

String

See Also

Recipient Property


SMTP DateStamp Property
DateStamp Property

Description

Return the current date in the format used by mail applications

Visual Basic

[form.]control.DateStamp

Remarks

The DateStamp property returns the current date and time in a format that is commonly used in mail applications. This property should be used in all date-related fields in the message header.

Data Type

String

See Also

Address Property, Recipient Property


SMTP Domain Property
Domain Property

Description

Set or return the current domain name

Visual Basic

[form.]control.Domain [= name$]

Remarks

The Domain property specifies the domain name of the local host. This property is used to identify the client to the server when a connection is established. Typically this property is the same value as the LocalName property.

Data Type

String

See Also

Action Property, Address Property, Recipient Property


SMTP Recipient Property
Recipient Property

Description

Set or return the address of a message recipient

Visual Basic

[form.]control.Recipient [= address$]

Remarks

The Recipient property serves two functions in the control, depending on the state of the client. If a message transaction has begun, the address is added to the recipient list for the message being composed each time the property is set.

If a message is not being composed, the Recipient property works in conjunction with expanding or verifying the address. In the case of the SMTP_ACTION_EXPAND action being used, the address is expanded by the server and the result overwrites the current property value. If the SMTP_ACTION_VERIFY action is used, the address is verified by the server, with the result returned in the ResultCode property.

Data Type

String

See Also

Action Property, Address Property


SMTP State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	SMTP_CLIENT_UNUSED	No connection established
1	SMTP_CLIENT_IDLE	Client connection is not active
2	SMTP_CLIENT_CONNECTING	Establishing connection with server
3	SMTP_CLIENT_ADDRESSING	Client is addressing the message
4	SMTP_CLIENT_COMPOSING	Client is composing the message
5	SMTP_CLIENT_SENDING	Client is sending the message
Data Type

Integer

See Also

IsBlocked Property


SMTP Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*AddressMail	*Connect	*Expand	*SendMail	*Write
*Cancel	*Disconnect	*Reset	*Verify
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


SMTP AddressMail Method
AddressMail Method

Description

Begin a new mail transaction

Visual Basic

[form.]control.AddressMail

Remarks

The AddressMail method begins a new mail transaction. After a connection is established with the remote host, this method should be invoked to begin addressing the mail. The Recipient property should then be set for each e-mail address. Once the message has been addressed, the header and body of the message can be created using the SendData property or Write method. When it is ready to send, the SendMail method should be used to deliver the message.

Return Value

A value of zero is returned if the application can begin addressing the message. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, SendMail Method


SMTP Expand Method
Expand Method

Description

Expand the specified e-mail address

Visual Basic

[form.]control.Expand address$

Remarks

This method requests that the server expand the specified e-mail address. The expanded address is copied back into the string passed as an argument to the method.

The address argument specifies the e-mail address to expand.

Return Value

A value of zero is returned if the address was expanded successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Verify Method


SMTP SendMail Method
SendMail Method

Description

Ends the mail transaction and delivers the message

Visual Basic

[form.]control.SendMail

Remarks

The SendMail method completes the mail transaction and delivers the message. This method should be invoked after the message has been addressed and the body of the message sent to the server through the SendData property or Write method.

Return Value

A value of zero is returned if the message was submitted successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, AddressMail Method


SMTP Verify Method
Verify Method

Description

Verifies that the specified e-mail address is valid

Visual Basic

[form.]control.Verify address$

Remarks

The address argument specifies the e-mail address to expand.

Return Value

A non-zero return value (True) indicates that the address is valid. A return value of zero (False) indicates that it is not. The validity of a given e-mail address is determined by the remote server, not the control.

See Also

Action Property, Expand Method


SMTP Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*Connect	*Disconnect	*LastError


SMTP Control Errors
  Value                   Description

    22201                   Invalid handle to SMTP client
    22202                   Invalid parameter passed to function
    22203                   Cannot initialize socket library
    22204                   Cannot allocate memory
    22205                   Cannot resolve host name
    22206                   Cannot create socket
    22207                   Cannot connect to remote server
    22208                   Cannot select socket
    22209                   Timeout reading socket
    22210                   Invalid SMTP server response
    22211                   Cannot read socket
    22212                   Cannot write socket
    22213                   Server connection is in use
    22214                   No return address specified
    22215                   No recipients specified
    22216                   Server receiving message data
    22217                   No message data received
    22218                   Server connection is closed
    22219                   Client operation was canceled


 Telnet Control
Properties      Methods      Events       Errors

Description

The Telnet control enables an application to establish a network connection with a remote host and interact with the host through a virtual terminal.

File Name

CSTNTCTL.VBX, CSTNT16.OCX, CSTNT32.OCX

Object Type

TelnetClient

Requirements

The Telnet control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the Telnet control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


Telnet Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	Index	*LocalAddress	*RemoteService	Top
*AutoResolve	*IsBlocked	*LocalEcho	*SendData	*Vendor
*Binary	*IsClosed	*LocalName	*SendLen	*Version
*Blocking	*IsReadable	Name	*Socket
*Connected	*IsWritable	*RecvData	*SocketError
*Handle	*LastError	*RecvLen	*State
*HostAddress	Left	*RecvNext	Tag
*HostName	*Library	*RemotePort	*Terminal


Telnet Action Property
Action Property

Description

Setting this property causes the Telnet client to take some action, such as establishing a connection with a remote server.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	TELNET_ACTION_CONNECT	Establish a connection with the remote host specified by the HostAddress or HostName properties.
2	TELNET_ACTION_DISCONNECT	Disconnect from the remote host
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Connected Property, State Property, Timeout Property


Telnet Binary Property
Binary Property

Description

Enable or disable binary input and output

Visual Basic

[form.]control.Binary [= { True | False } ]

Remarks

The Binary property enables or disables the exchange of binary data between the client and server. If set to False, all characters have the high-bit stripped off. The default value is True, which specifies that data is to be received unchanged from the remote host.

Data Type

Integer (Boolean)

See Also

LocalEcho Property


Telnet LocalEcho Property
LocalEcho Property

Description

Enable or disable the echoing of characters by the remote host

Visual Basic

[form.]control.LocalEcho [= { True | False } ]

Remarks

The LocalEcho property enables or disables the echoing of characters by the remote host. If set to True, the remote host will be instructed to not echo characters, making the client responsible for displaying user input. The default value for this property is False, specifying that the server should echo user input back to the client.

Data Type

Integer (Boolean)

See Also

Binary Property


Telnet State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. This property should be checked on blocking controls to determine if the control is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	SOCKET_UNUSED	The socket has not been created. Attempts to use the socket will generate an error.
1	SOCKET_IDLE	The socket exists, but is not currently in use. A blocking socket operation can be executed at this point.
2	SOCKET_LISTENING	The socket is listening for connections from remote hosts
3	SOCKET_CONNECTING	The socket is in the process of connecting to a remote host
4	SOCKET_RECEIVING	The socket is in the process of receiving data
5	SOCKET_SENDING	The socket is in the process of sending data
6	SOCKET_CLOSING	The socket is being closed. Subsequent attempts to access the socket will result in an error.
Note that for non-blocking sockets, the only possible states that may be returned are SOCKET_UNUSED, SOCKET_IDLE or SOCKET_CLOSING.

Data Type

Integer

See Also

IsBlocked Property


Telnet Terminal Property
Terminal Property

Description

Set or return the terminal type used by the control

Visual Basic

[form.]control.Terminal [= termtype$ ]

Remarks

The Terminal property specifies the terminal type of the remote host for display purposes. When used in conjunction with the terminal emulation control, this property should be set to "ansi" or an equivalent terminal type.

Data Type

String

See Also

UserName Property


Telnet Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*Disconnect	*Read	*Write
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


Telnet Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Connect	*Disconnect	*LastError	*Read	*Write


Telnet Control Errors
  Value                   Description

    22101                   No free handles
    22102                   Cannot allocate memory
    22103                   Not session owner
    22104                   Cannot initialize network
    22105                   Invalid host name
    22106                   Cannot create socket
    22107                   Cannot connect to remote server
    22108                   Cannot get peer information
    22109                   Invalid parameter passed to function
    22110                   Invalid client handle
    22111                   Cannot select socket
    22112                   Cannot read socket
    22113                   Read buffer overflow
    22114                   Cannot write socket
    22115                   Write buffer underflow
    22116                   Connection is in use
    22117                   Connection is not in use
    22118                   Timeout waiting for socket
    22119                   Internal synchronization error
    22120                   Unsupported option
    22121                   Remote server closed connection


 Terminal Emulation Control
Properties    Methods    Events

Description

The terminal emulation control allows an application to provide ANSI terminal emulation services.

File Name

CSNVTCTL.VBX, CSNVT16.OCX, CSNVT32.OCX

Object Type

Terminal

Requirements

The terminal emulation control requires Microsoft Windows 3.1 or later and Visual Basic 3.0 or later. The OLE controls require Visual Basic 4.0 or another compatible container.

Distribution

When you distribute your application that uses the terminal emulation control, you should install the appropriate file in the Windows system directory.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


Terminal Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*Cursor	FontSize	*Rows
*Attribute	*CursorStyle	ForeColor	*SelLength
*AutoWrap	*CursorX	Height	*SelStart
BackColor	*CursorY	hWnd	*SelText
*Bell	DragIcon	Index	Tag
*BoldColor	DragMode	*KeyMap	Top
BorderStyle	*Emulation	Left	Visible
*CellHeight	Enabled	MousePointer	Width
*CellWidth	FontBold	*NewLine
*Columns	FontName	*Output


Terminal Action Property
Action Property

Description

Setting this property causes the emulator to take some action, such as clearing the display.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	TERM_ACTION_CLRSCR	Clear the display and clear all text attributes
2	TERM_ACTION_CLREOL	Clear the display to the end of the current line
3	TERM_ACTION_INSLINE	Insert a line of text at the current position
4	TERM_ACTION_DELLINE	Delete a line of text at the current position
5	TERM_ACTION_SCROLLUP	Scroll the display up one line of text
6	TERM_ACTION_SCROLLDN	Scroll the display down one line of text
7	TERM_ACTION_REFRESH	Refresh the display by clearing and then redrawing the display.
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Columns Property, Emulation Property, Rows Property


Terminal Attribute Property
Attribute Property

Description

Set or return the current display attribute for the terminal emulator

Visual Basic

[form.]control.Attribute [ = attrib% ]

Remarks

The Attribute property can be used to determine the current display attributes, or to change the current attribute for subsequent text. The following table lists the attributes that are recognized by the control.

Value	Description
0	Normal display, no attributes enabled
1	Reverse video attribute
2	Bold attribute (use BoldColor color to display text)
4	Dim attribute
8	Blink attribute (not supported)
16	Underline attribute
32	Graphics attribute
The SOCKET_CONNECT and SOCKET_ACCEPT actions are always blocking (i.e.: the value of the Blocking property is ignored) and will use the Timeout property to determine the amount of time to wait until the action times-out.

Data Type

Integer

See Also

BoldColor Property, CursorStyle Property


Terminal AutoWrap Property
AutoWrap Property

Description

Enable or disable the wrapping of text in the emulation window

Visual Basic

[form.]control.AutoWrap [= { True | False } ]

Remarks

The AutoWrap property enables or disables the wrapping of text in the emulation window. If set to True, when text reaches last column in the display, the cursor is re-positioned to the first column on the next line. If set to False, any text displayed beyond the last column is discarded.

Data Type

Integer

See Also

Bell Property, Columns Property, Emulation Property, Rows Property


Terminal Bell Property
Bell Property

Description

Enable or disable the audible bell

Visual Basic

[form.]control.Bell [= { True | False } ]

Remarks

The Cursor property enables or disables the display of the cursor in the emulation window. The default property value is True.

Data Type

Integer (Boolean)

See Also

AutoWrap Property


Terminal BoldColor Property
BoldColor Property

Description

Determines the color to use in displaying bold text

Visual Basic

[form.]control.BoldColor [ = color ]

Remarks

Visual Basic uses the Microsoft Windows environment RGB scheme for colors.  Each property has the following ranges of settings:

Range of settings	Description
Normal RGB colors	Colors specified by using the Color palette, or by using the RGB or QBColor functions in code.
System default colors	Colors specified with system color constants from CONSTANT.TXT, a Visual Basic file that specifies system defaults.  The Windows environment substitutes the user's choices as specified in the user's Control Panel settings.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF).  The high byte of a number in this range equals 0; the lower three bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively.  The red, green, and blue components are each represented by a number between 0 and 255 (&HFF).  If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel and enumerated in CONSTANT.TXT.

Data Type

Long (Color)

See Also

BackColor Property, ForeColor Property


Terminal CellHeight Property
CellHeight Property

Description

Return the height of a text cell

Visual Basic

[form.]control.CellHeight

Remarks

The CellHeight property returns the height of a text cell in Twips. This value can be used in calculating the minimum height of the display window in order to display all lines of text.

Data Type

Integer

See Also

CellWidth Property


Terminal CellWidth Property
CellWidth Property

Description

Return the width of a text cell

Visual Basic

[form.]control.CellWidth

Remarks

The CellWidth property returns the width of a text cell in Twips. This value can be used in calculating the minimum width of the display window in order to display all text columns.

Data Type

Integer

See Also

CellHeight Property


Terminal Columns Property
Columns Property

Description

Set or return the number of columns in the emulation display

Visual Basic

[form.]control.Columns [= cols ]

Remarks

The Columns property returns the number of columns in the emulation window, or allows the application to change the number of columns. Currently, the number of columns may only be set to 80 or 132.

Note Changing the number of columns in the display causes the current display to be invalidated, and the window will be cleared.

Data Type

Integer

See Also

Rows Property


Terminal Cursor Property
Cursor Property

Description

Enable or disable the display of the cursor in the emulation window

Visual Basic

[form.]control.Cursor [= { True | False } ]

Remarks

The Cursor property enables or disables the display of the cursor in the emulation window. The default property value is True.

Data Type

Integer (Boolean)

See Also

CursorStyle Property, Emulation Property


Terminal CursorStyle Property
CursorStyle Property

Description

Set or return the style of cursor used in the emulator

Visual Basic

[form.]control.CursorStyle [= style ]

Remarks

The CursorStyle property determines how the cursor is displayed in the emulation window. A value of 0 indicates that the cursor should be an underline, while a value of 1 indicates that the cursor should be a full height block character.

Data Type

Integer

See Also

Cursor Property


Terminal CursorXY Property
CursorX, CursorY Property

Description

Set or return the current cursor position in the display

Visual Basic

[form.]control.CursorX [= col % ]
[form.]control.CursorY [= row %  ]

Remarks

The CursorX and CursorY properties return the current position of the cursor in the display, or can be used to change the current position. The current position is given in columns or rows, and indicates where the next text character will be displayed.

Data Type

Integer

See Also

Cursor Property, CursorStyle Property


Terminal Emulation Property
Emulation Property

Description

Set or return the emulation used by the control

Visual Basic

[form.]control.Emulation [= emtype% ]

Remarks

The Emulation property can be used to set the type of emulation performed by the control. Currently there are two values recognized by the control. If set to 0, the control performs no emulation and displays all characters in the control window. If set to 1, the control recognizes ANSI escape sequences and will perform functions such as clearing the display, setting text attributes and so on.

Data Type

Integer

See Also

AutoWrap Property, Cursor Property, Output Property


Terminal KeyMap Property
KeyMap Property

Description

Set or return the character sequence mapped to a special key

Visual Basic

[form.]control.KeyMap(index) [= value$ ]

Remarks

The KeyMap property allows the application to define character sequences that should be mapped to special keys. When a special key is pressed in the emulation window and there is an entry for it in the key map, the KeyMapped event is fired. The following special keys are recognized:

Value	Constant	Description
0	NVT_F1	F1 function key
1	NVT_F2	F2 function key
2	NVT_F3	F3 function key
3	NVT_F4	F4 function key
4	NVT_F5	F5 function key
5	NVT_F6	F6 function key
6	NVT_F7	F7 function key
7	NVT_F8	F8 function key
8	NVT_F9	F9 function key
9	NVT_F10	F10 function key
10	NVT_F11	F11 function key
11	NVT_F12	F12 function key
12	NVT_SF1	Shift F1 function key
13	NVT_SF2	Shift F2 function key
14	NVT_SF3	Shift F3 function key
15	NVT_SF4	Shift F4 function key
16	NVT_SF5	Shift F5 function key
17	NVT_SF6	Shift F6 function key
18	NVT_SF7	Shift F7 function key
19	NVT_SF8	Shift F8 function key
20	NVT_SF9	Shift F9 function key
21	NVT_SF10	Shift F10 function key
22	NVT_SF11	Shift F11 function key
23	NVT_SF12	Shift F12 function key
24	NVT_ENTER	Enter key
25	NVT_ERASE	Backspace key
26	NVT_UP	Cursor up key
27	NVT_DOWN	Cursor down key
28	NVT_LEFT	Cursor left key
29	NVT_RIGHT	Cursor right key
30	NVT_INSERT	Insert key
31	NVT_DELETE	Delete key
32	NVT_HOME	Home key
33	NVT_END	End key
34	NVT_PGUP	Page up key
35	NVT_PGDN	Page down key
Data Type

String

See Also

KeyMapped Event


Terminal NewLine Property
NewLine Property

Description

Determine how carriage returns and linefeeds are displayed

Visual Basic

[form.]control.NewLine [= value%  ]

Remarks

The NewLine property controls how carriage returns and linefeeds are processed by the emulator. The following values may be used:

Value	Description
0	A carriage return positions the cursor to the first column, and a linefeed advances the cursor to the next row, scrolling the display if necessary. This is the default value.
1	A carriage return positions the cursor to the first column and advances to the next row, scrolling the display if necessary.
2	A linefeed positions the cursor to the first column and advances to the next row, scrolling the display if necessary.
Data Type

Integer

See Also

Columns Property


Terminal Output Property
Output Property

Description

Display the string in the terminal emulation window

Visual Basic

[form.]control.Output = output$

Remarks

Assigning the Output property causes the string to be displayed in the emulation window. If the Emulation property is non-zero, escape sequences embedded in the string are processed by the control.

Data Type

String

See Also

Emulation Property


Terminal Rows Property
Rows Property

Description

Set or return the number of rows in the emulation display

Visual Basic

[form.]control.Rows [= rows ]

Remarks

The Rows property returns the number of rows in the emulation window, or allows the application to change the number of rows. Currently, the number of rows may only be set to 24 or 25.

Note Changing the number of rows in the display causes the current display to be invalidated, and the window will be cleared.

Data Type

Integer

See Also

Columns Property


Terminal Select Property
SelLength, SelStart, SelText Property

Description

Select and return the contents of the emulation display

Visual Basic

[form.]control.SelLength [= bytes ]
[form.]control.SelStart [= offset ]
[form.]control.SelText

Remarks

These properties are used to select a portion of the emulation display and return the text displayed at that location. The SelStart property indicates where on the display the text should be read from. To convert the cursor position to an offset, multiply the y-position by the number of columns and add the x-position. The SelLength property determines the number of characters to copy from the starting position. Reading the SelText property returns the text displayed at the selected location.

Note The SelText property cannot be used to overwrite a portion of the display. Assigning a value to this property will generate an error.

Data Type

SelLength - Integer, SelStart - Integer, SelText - String

See Also

Columns Property, CursorX Property, CursorY Property, Rows Property


Terminal Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Clear	*DelLine	Refresh	*ScrollUp
*ClearEol	*InsLine	*ScrollDown
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


Terminal Clear Method
Clear Method

Description

Clear the terminal emulation window

Visual Basic

[form.]control.Clear

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal ClearEol Method
ClearEol Method

Description

Erase all characters from the current column to the end of the line

Visual Basic

[form.]control.ClearEol

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal DelLine Method
DelLine Method

Description

Delete the current line in the terminal emulation display

Visual Basic

[form.]control.DelLine

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal InsLine Method
InsLine Method

Description

Insert an empty line at the current position in the terminal emulation display

Visual Basic

[form.]control.DelLine

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal ScrollDown Method
ScrollDown Method

Description

Scroll the display down by one line

Visual Basic

[form.]control.ScrollDown

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal ScrollUp Method
ScrollUp Method

Description

Scroll the display up by one line

Visual Basic

[form.]control.ScrollUp

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Terminal Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Change	DragOver	KeyPress	MouseMove
Click	GotFocus	KeyUp	MouseUp
DblClick	KeyDown	LostFocus	*Resize
DragDrop	*KeyMapped	MouseDown


Terminal KeyMapped Event
KeyMapped Event

Description

The KeyMapped event is generated when a mapped key is pressed in the emulation window

Visual Basic

Sub control_KeyMapped ([Index As Integer,] KeyCode As Integer, Shift As Integer, KeyString As String)

Remarks

This event is generated when the user presses a special key while the emulation window has focus, and that key is mapped to a string using the KeyMap property array.

The KeyCode argument identifies the special key that has been pressed. Refer to the KeyMap property for a table of key values.

The Shift argument indicates the state of the Shift, Control and ALT keys. A value of 1 indicates that the shift key is pressed, a value of 2 means the control key is pressed and a value of 4 means the ALT key is pressed. These values may be combined if multiple keys are being held down at the same time.

The KeyString argument contains the value that the special key has been mapped to.

See Also

KeyMap Property


 Web Browser Control
Properties     Methods      Events     Errors

Description

The Web browser client control allows the developer to display HTML (Hypertext Markup Language) files and establish connections with remote servers to retrieve these documents.

File Name

CSWEBCTL.VBX, CSWEB16.OCX, CSWEB32.OCX

Object Type

WebClient

Remarks

The Web browser  control can be used as both a viewer of HTML documents, and as a tool to retrieve documents and other resources from an HTTP server. The control supports the HTML 2.0 specification and some extensions used by the Netscape browser and Microsoft's Internet Explorer.

Requirements

The Web client control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the Web client control, you should install the appropriate file in the Windows system directory. For the 16-bit controls, the  CSIMGL16.DLL file must be installed, and for the 32-bit control, the CSIMGL32.DLL file must be installed. If this library is not present, the control will be unable to display images.

Copyright

Copyright © 1996, Catalyst Development Corporation. All rights reserved.


Web Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Action	*Connected	*ImageIndex	*LocalFile	*State
*ActiveLink	DragIcon	*ImageTitle	*LocalName	TabIndex
*Anchor	DragMode	*IndexFile	MousePointer	TabStop
*AuthenticName	Enabled	*IsBlocked	Name	Tag
*AuthenticPassword	*FontFixed	*IsCached	*Parse	*Timeout
*AutoLoad	*FontHeading	*IsIndex	*Pragma	*Title
*AutoRedirect	*FontNormal	*IsLoading	*Private	Top
*AutoRefresh	*FontScale	*IsLocal	*ProxyHost	Visible
*AutoResolve	ForeColor	*IsProxy	*ProxyPort	Width
BackColor	Height	*Keyword	*RemoteAccess	*UserAgent
*Base	*History	*LastError	*RemoteFile	*UserName
*Blocking	*HistorySize	Left	*RemotePort	*Vendor
BorderStyle	*HostAddress	*Library	*RemoteService	*Version
*CacheDir	*HostName	*Link	*Resource
*CacheFile	*Image	*LinkColor	*ResultCode
*CacheSize	*ImageCount	*LinkCount	*Socket
*CacheTimeout	*ImageFile	*LocalAddress	*SocketError


Web Action Property
Action Property

Description

Setting this property causes the control to take some action, such as loading an HTML document.

Visual Basic

[form.]control.Action = action%

Remarks

The following table lists the actions that the control may take:

Value	Constant	Description
1	WEB_ACTION_LOAD	Load the resource specified by the Resource and related properties.
2	WEB_ACTION_RELOAD	Reload the specified resource without using the control cache.
3	WEB_ACTION_UNLOAD	Unload the current document from memory and clear the display.
4	WEB_ACTION_NEXT	Retrieve the next document in the control history list.
5	WEB_ACTION_PREV	Retrieve the previous document from the control history list.
6	WEB_ACTION_CANCEL	Cancel the loading of a document. This action has no effect if the document has already been loaded, or if the Blocking property is True.
7	WEB_ACTION_RESET	Reset the control, unloading the current document and removing all entries from the control cache and history list.
8	WEB_ACTION_REFRESH	Refresh the display, reloading all in-line graphics images. This action is typically used to update the display after the Parse property has been used.
9	WEB_ACTION_SEARCH	This action causes the string assigned to the Keyword property to be sent to the remote host. If the document is not a searchable index, this action is ignored.
10	WEB_ACTION_LINEUP	Scroll the document up one line. This action has no effect if the client area is large enough to contain the entire document.
11	WEB_ACTION_LINEDOWN	Scroll the document down one line. This action has no effect if the client area is large enough to contain the entire document.
12	WEB_ACTION_PAGEUP	Scroll the document up one page. This action has no effect if the client area is large enough to contain the entire document.
13	WEB_ACTION_PAGEDOWN	Scroll the document down one page. This action has no effect if the client area is large enough to contain the entire document

If a local resource is specified, the WEB_ACTION_LOAD property will cause the resource to be immediately loaded. If the resource is remote, the action taken depends on the Blocking property. If the Blocking property is True, then execution of the program resumes after the document has been loaded. Otherwise, the document is loaded asynchronously and execution of the program resumes immediately.

Note  These actions only pertain to HTML documents, and not in-line graphics images. If the document references images, those images will be loaded automatically, unless the AutoLoad property is False.

Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

AutoLoad Property, Blocking Property, IsLoading Property, Resource Property, State Property,Load Event


Web ActiveLink Property
ActiveLink Property

Description

Return the number of the currently active hyperlink

Visual Basic

[form.]control.ActiveLink

Remarks

The ActiveLink read-only property returns a number which identifies the hyperlink which the user has the mouse pointer positioned over. If the pointer is not positioned over a hyperlink, a value of 0 is returned. This number can be used as an index into the Link property array to determine the URL of the resource being linked to.

Data Type

Integer

See Also

Link Property


Web Anchor Property
Anchor Property

Description

Set or return the current document anchor string.

Visual Basic

[form.]control.Anchor [= anchor$]

Remarks

The Anchor property sets or returns the anchor for the current document. Setting this property to the value will cause the current location in the document to change to the anchored text.

Data Type

String

See Also

Resource Property


Web AuthenticName Property
AuthenticName Property

Description

Set or return the authentic name of the current user.

Visual Basic

[form.]control.AuthenticName [= name$]

Remarks

The AuthenticName property is used to define the current user name for basic access authentication.

Data Type

String

See Also

AuthenticPassword Property


Web AuthenticPassword Property
AuthenticPassword Property

Description

Set or return the authentic password for the current user.

Visual Basic

[form.]control.AuthenticPassword [= password$]

Remarks

The AuthenticPassword property defines the password for the current user as part of the basic access authentication scheme.

Data Type

String

See Also

AuthenticName Property


Web AutoLoad Property
AutoLoad Property

Description

Enable or disable the automatic loading of in-line graphics images.

Visual Basic

[form.]control.AutoLoad [= boolean ]

Remarks

The AutoLoad property controls how in-line graphics images are processed with HTML documents. If True, all images referenced in the document are automatically loaded after the document itself. Otherwise, a standard icon is used to represent the unloaded graphic image.

Data Type

Integer (Boolean)

See Also

Action Property


Web AutoRedirect Property
AutoRedirect Property

Description

Enable or disable the automatic redirection of resources.

Visual Basic

[form.]control.AutoRedirect [= boolean ]

Remarks

The AutoRedirect property controls how redirected resources are loaded by the control. By default, a redirected resource (a resource which has moved) is automatically located and loaded by the control. If this property is set to False, an attempt to load a redirected resource will fail with an error. It then becomes the responsibility of the application to locate and load the resource.

Data Type

Integer (Boolean)

See Also

Action Property, Redirect Event


Web AutoRefresh Property
AutoRefresh Property

Description

Enable or disable automatic refreshing of the display.

Visual Basic

[form.]control.AutoRefresh [= boolean ]

Remarks

The AutoRefresh property determines if the control automatically refreshes the display when HTML text is parsed by the control. If enabled, the display is refreshed immediately after the Parse property is set. Otherwise, the display is not refreshed until the WEB_ACTION_REFRESH action is called by the application. This can be useful to avoid the overhead of redrawing the display if multiple lines of text are being parsed at one time.

Data Type

Integer (Boolean)

See Also

Action Property, Parse Property


Web Base Property
Base Property

Description

Set or return the base URL for the current document.

Visual Basic

[form.]control.Base [= URL$]

Remarks

The Base property sets or returns the base URL for the current document, and is used whenever the document references a resource using a relative URL. If the document specifies another base URL, this property is modified automatically.

Data Type

String

See Also

Resource Property


Web CacheDir Property
CacheDir Property

Description

Set or return the directory used for the local resource cache

Visual Basic

[form.]control.CacheDir [= path$]

Remarks

The CacheDir property is used to specify the directory where HTML document and image files are cached. Each instance of the control has it's own private cache which is used to speed the loading of documents and in-line graphics images.

By default, the directory specified by the TEMP environment variable is used. If it's undefined, the Windows directory is used instead.

Note Changing the cache directory will cause the current cache to be invalidated and all cached resources will be deleted from the local system.

Data Type

String

See Also

CacheFile Property, CacheSize Property, IsCached Property


Web CacheFile Property
CacheFile Property

Description

Return the name of the current cache file.

Visual Basic

[form.]control.CacheFile

Remarks

The CacheFile read-only property returns the local filename of the cached resource, and should be considered valid only if the IsCached property is True.

Data Type

String

See Also

CacheDir Property, CacheSize Property, IsCached Property


Web CacheSize Property
CacheSize Property

Description

Set or return the size of the local resource cache.

Visual Basic

[form.]control.CacheSize [= size ]

Remarks

The CacheSize property sets the maximum number of entries that may be stored in the local cache. Each file that is retrieved from the remote host, such as HTML documents and graphics images, is stored in the local cache.

Note Changing the size of the cache will cause the current cache to be invalidated and all cached resources will be deleted from the local system.

Data Type

Integer

See Also

CacheDir Property, CacheFile Property, CacheTimeout Property, IsCached Property


Web CacheTimeout Property
CacheTimeout Property

Description

Set or return the number of seconds a cache entry is valid.

Visual Basic

[form.]control.CacheTimeout [= seconds ]

Remarks

The CacheTimeout property controls how long a cached resource is considered valid. By default, a cache entry is valid for five minutes (300 seconds). Setting the timeout value to zero causes cached resources to be valid until the control is unloaded.

Data Type

Integer

See Also

CacheDir Property, CacheFile Property, CacheSize Property


Web Font Property
FontFixed, FontHeading, FontNormal Property

Description

Set or return the font name to be used when displaying text.

Visual Basic

[form.]control.FontFixed [ = fontname$ ]
[form.]control.FontHeading [ = fontname$ ]
[form.]control.FontNormal [ = fontname$ ]

Remarks

The properties determine the fonts used by the control to display text. The font specified by the FontFixed property is used when a fixed-width font is specified in the document, the FontHeading font is used when a heading is specified, and the FontNormal font is used in all other cases. By default, the FontNormal and FontHeading font is Times New Roman, and the FontFixed font is Courier New.

Data Type

String

See Also

FontScale Property


Web History Property
History Property

Description

Return a document URL from the control history list.

Visual Basic

[form.]control.History(index)

Remarks

Each instance of the History control stores a history of those documents that have been loaded. If the index argument is greater than the current number of entries in the history list, an empty string is returned.

Data Type

String

See Also

HistorySize Property


Web HistorySize Property
HistorySize Property

Description

Set or return the maximum number of URL's stored in the history list.

Visual Basic

[form.]control.HistorySize [ = size ]

Remarks

The HistorySize property sets the number of document URL's which are stored in the control's history list.

Data Type

Integer

See Also

Action Property, History Property


Web IndexFile Property
IndexFile Property

Description

Set or return the name of the default index file

Visual Basic

[form.]control.IndexFile [ = string ]

Remarks

The IndexFile property sets the default name of the index file. This is the file name that is used when one is not explicitly specified in a local path. For example:

file:/webdocs/info/

Since no file name was explictly given, the IndexFile property is appended to the path. By default, the property value is index.htm.

Note This property is only used when loading local files. The index file name on a remote server is determined by the server, not the client.

Data Type

String

See Also

Base Property, IsLocal Property, Resource Property


Web IsCached Property
IsCached Property

Description

Determine if the current resource is cached on the local system.

Visual Basic

[form.]control.IsCached

Remarks

This property returns True if the current resource was loaded from the control's cache.

Data Type

Integer (Boolean)

See Also

CacheDir Property, CacheFile Property, CacheTimeout Property


Web IsIndex Property
IsIndex Property

Description

Determine if the current document is a searchable index

Visual Basic

[form.]control.IsIndex

Remarks

This read-only property returns True if the current document is a searchable index, as indicated by the <isindex> tag. If the document is a searchable index, then the Keyword property can be used to set the keyword to search for.

Data Type

Integer (Boolean)

See Also

Action Property, Keyword Property


Web IsLoading Property
IsLoading Property

Description

Determine if a document is loading

Visual Basic

[form.]control.IsLoading

Remarks

This property returns True while a document is being loaded, and during the loading of any in-line graphic images.

Data Type

Integer (Boolean)

See Also

Action Property, AutoLoad Property, Change Event, Load Event, QueryLoad Event


Web IsLocal Property
IsLocal Property

Description

Determine if the current resource is local to the system.

Visual Basic

[form.]control.IsLocal [= boolean ]

Remarks

This property returns True if the current resource is local to the system. Setting the value of this property affects the HTTP_ACTION_LOAD property by determining which property, LocalFile or RemoteFile, should be used to determine the name of the file to load.

Note  Setting the LocalFile or RemoteFile properties will automatically change the value of this property appropriately. This property is also automatically updated when the Resource property is set.

Data Type

Integer (Boolean)

See Also

LocalFile Property, RemoteFile Property, Resource Property


Web IsProxy Property
IsProxy Property

Description

Enable or disable the use of a proxy server to retrieve documents

Visual Basic

[form.]control.IsProxy [= boolean ]

Remarks

This property controls how the control retrieves documents from a remote host. If True, then the ProxyHost and ProxyPort properties are used to connect to a proxy server, and all resources are requested through that server. The default value for this property is False, which causes resources to be loaded directly from the host they are stored on.

Data Type

Integer (Boolean)

See Also

ProxyHost Property, ProxyPort Property


Web Keyword Property
Keyword Property

Description

Specify the keywords used to seach a document

Visual Basic

[form.]control.Keyword  [ =string$ ]

Remarks

The Keyword property is used to define the keywords used to search a document. This only has an effect if the document is searchable, as determined by the use of the <isindex> tag.

The IsIndex property can be used to determine if the current document is a searchable index or not.

Data Type

String

See Also

Action Property, IsIndex Property


Web Link Property
Link Property

Description

Return the URL for the specified hyperlink

Visual Basic

[form.]control.Link(index)

Remarks

The Link property returns the URL for the hyperlink specified by the index argument. The index may be a value in the range of 1 through the number of links in the document. An index value of 0 always returns an empty string.

This property array may be used in conjunction with the ActiveLink property to determine the URL of a hyperlink that the mouse pointer is currently positioned over.

Data Type

String

See Also

ActiveLink Property, LinkCount Property


Web LinkColor Property
LinkColor Property

Description

Determines the color to use in displaying hypertext links in a document

Visual Basic

[form.]control.LinkColor [ = color ]

Remarks

Visual Basic uses the Microsoft Windows environment RGB scheme for colors.  Each property has the following range of settings:

Range of settings	Description
Normal RGB colors	Colors specified by using the Color palette, or by using the RGB or QBColor functions in code.
System default colors	Colors specified with system color constants from CONSTANT.TXT, a Visual Basic file that specifies system defaults.  The Windows environment substitutes the user's choices as specified in the user's Control Panel settings.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF).  The high byte of a number in this range equals 0; the lower three bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively.  The red, green, and blue components are each represented by a number between 0 and 255 (&HFF).  If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel and enumerated in CONSTANT.TXT.

Note The link color, as well as the color of the background and text may be changed from within the document. If the document does specify a color, that value overrides this property.

Data Type

Long (Color)

See Also

ActiveLink Property, Link Property, LinkCount Property


Web LinkCount Property
LinkCount Property

Description

Return the number of hyperlinks in the current document

Visual Basic

[form.]control.LinkCount

Remarks

This read-only property returns the number of hyperlinks in the current document. This property may be used in conjunction with the Link property to enumerate the URL of each hyperlink.

Data Type

Integer

See Also

ActiveLink Property, Link Property, LinkColor Property


Web LocalFile Property
LocalFile Property

Description

Set or return the file name to load from the local system

Visual Basic

[form.]control.LocalFile [ = filename$ ]

Remarks

This property is used to specify the name of a local file to be loaded by the control, and setting it automatically causes the IsLocal property to be set to True.

Data Type

String

See Also

IsLocal Property, Resource Property


Web Parse Property
Parse Property

Description

Parse a string of HTML text and append the result to the current page

Visual Basic

[form.]control.Parse = htmltext$

Remarks

Assigning a string to the Parse property causes the control to parse that string for HTML tags and appends the result to the current page being viewed. If no page is currently loaded, an empty page is created. Use of this property allows pages to be created or modified dynamically by the application.

Note This is a write-only property. Attempting to assign this property to a variable will result in a runtime error. The contents of a document modified or created using the Parse property are not saved by the control and will be destroyed when another page is loaded.

Data Type

String

See Also

AutoRefresh Property


Web Pragma Property
Pragma Property

Description

Set or return the pragma string sent to the remote server

Visual Basic

[form.]control.Pragma [ = pragmastring$ ]

Remarks

This property is used when requesting a resource from a remote HTTP server. If set, the Pragma field is included in the request header.

Currently, the only string recognized by the server is "no-cache", indicating that a caching proxy server must forward the request to the origin server, even if it has a cached copy of what is being requested.

Data Type

String

See Also

UserAgent Property, UserName Property


Web Private Property
Private Property

Description

Determine if private information about the client be included in a request

Visual Basic

[form.]control.Private [ = { True | False } ]

Remarks

The Private property determines if certain fields are included in the request header sent to a remote HTTP server. If True, then no information about the current user (including the user name or where the document was referenced from) will be included in the request.

Data Type

Integer (Boolean)

See Also

UserName Property


Web ProxyHost Property
ProxyHost Property

Description

Set or return the name of the proxy host

Visual Basic

[form.]control.ProxyHost [= hostname$]

Remarks

This property should be set to the name of the remote proxy server. This property is only referenced if the IsProxy property is True. Either a host name or IP address may be assigned to this property.

Data Type

String

See Also

IsProxy Property, ProxyPort Property


Web ProxyPort Property
ProxyPort Property

Description

Set or return the port number for a proxy server connection

Visual Basic

[form.]control.ProxyPort [= portno%]

Remarks

This property is used to set the port number that the control will use to establish a connection with the proxy server. This property is only used if the IsProxy property is True.

Data Type

Integer

See Also

IsProxy Property, ProxyHost Property


Web RemoteAccess Property
RemoteAccess Property

Description

Determine if the control can access files on a remote host

Visual Basic

[form.]control.RemoteAccess [ = { True | False } ]

Remarks

Setting the RemoteAccess property to False prevents the control from attempting to load a resource from a remote host. In effect, all document references are treated as if they are local to the system, regardless of the URL.

Data Type

Integer (Boolean)

See Also

Action Property, IsLocal Property, LocalFile Property, Resource Property


Web RemoteFile Property
RemoteFile Property

Description

Set or return the name of a file on a remote host

Visual Basic

[form.]control.RemoteFile [ = filename$ ]

Remarks

This property specifies the name of the file to retrieve from a remote host, and setting it causes the IsLocal property to be set to False.

Note The remote file name should always begin with a slash, otherwise the remote server may return an error indicating that the resource could not be located.

Data Type

String

See Also

HostAddress Property, HostName Property, IsLocal Property, LocalFile Property, Resource Property


Web Resource Property
Resource Property

Description

Set or return the URL of the current resource

Visual Basic

[form.]control.Resource [ = urlstring$ ]

Remarks

The Resource property is used to parse a URL, or return the URL of the current resource. If a URL is assigned to this property, the control parses it and sets the appropriate properties, such as the HostName, RemotePort and RemoteFile properties.

Reading the Resource property causes a URL to be constructed based on the current settings of the following properties:

Property Name	Data Type	Description
Anchor	String	The name of the anchor being referenced in the loaded document.
HostAddress	String	The IP address, in dot-notation, of the remote HTTP server. Only used if the IsLocal property is False.
HostName	String	The name of the remote HTTP server, if it can be determined. Only used if the IsLocal property is False.
IsLocal	Integer (Boolean)	Detemines if the specified resource is local to the client system. This property is set based on the method specified in the URL.
LocalFile	String	The file name of the local resource. Only used if the IsLocal property is True.
RemoteFile	String	The file name of the remote resource. Only used if the IsLocal property is False.
RemotePort	Integer	Specifies the port number of the remote server. Only used if the IsLocal property is False.
RemoteService	String	Specifies the service name of the remote port, if available. Only used if the IsLocal property is False.
Data Type

String

See Also

Action Property


Web State Property
State Property

Description

Return the current state of the control

Visual Basic

[form.]control.State

Remarks

This read-only property returns the state of the control. The possible values returned by this property are:

Value	Constant	Description
1	HTTP_CLIENT_IDLE	No resource is currently being loaded by the control.
2	HTTP_CLIENT_CONNECT	The control is attempting to connect to a remote server.
3	HTTP_CLIENT_COMMAND	The control has sent the request to the server and is awaiting a response.
4	HTTP_CLIENT_LOAD	The control is loading a resource, either from the local system or a remote host
5	HTTP_CLIENT_UNLOAD	The control is unloading the current resource
Note that if the Blocking property is True, the only possible states that may be returned are HTTP_CLIENT_IDLE or HTTP_CLIENT_LOAD.

Data Type

Integer

See Also

Blocking Property, IsBlocked Property, IsLocal Property


Web Title Property
Title Property

Description

Returns the title of the current document

Visual Basic

[form.]control.Title

Remarks

The Title property returns the title of the document as specified by the <title> tag.

Data Type

String


Web UserAgent Property
UserAgent Property

Description

Set or return the name of the client application

Visual Basic

[form.]control.UserAgent [ = agent$ ]

Remarks

Setting UserAgent property allows the developer to provide information to a remote server about the application requesting the resource. The string should contain the name of the application, with an optional slash and version designator. For example, a valid property value would be "MyProgram/1.0".

Typically, this information is used by servers for statistical purposes, tracing protocol violations and the automated recognition of specific user agents.

Note The user agent string should be short and to the point. It should not contain advertising information or other non-essential information.

Data Type

String

See Also

Pragma Property, UserName Property


Web Image Property
Image Property

Description

Return the URL for the specified image

Visual Basic

[form.]control.Image(index)

Remarks

The Image property returns the URL for the image specified by the index argument. The index may be a value in the range of 1 through the number of images in the document. An index value of 0 always returns an empty string.

This property array may be used in conjunction with the ImageIndex property to determine the URL of an image that the mouse pointer is currently positioned over.

Data Type

String

See Also

ImageCount Property, ImageFile Property, ImageIndex Property, ImageTitle Property


Web ImageCount Property
ImageCount Property

Description

Return the number of images in the current document

Visual Basic

[form.]control.ImageCount

Remarks

This read-only property returns the number of images in the current document. This property may be used in conjunction with the Image property to enumerate the URL of each image.

Data Type

Integer

See Also

Image Property, ImageFile Property, ImageIndex Property, ImageTitle Property


Web ImageFile Property
ImageFile Property

Description

Return the cache file name for the specified image

Visual Basic

[form.]control.ImageFile(index)

Remarks

The Image property returns the cache file name for the image specified by the index argument. The index may be a value in the range of 1 through the number of images in the document. An index value of 0 always returns an empty string.

This property array may be used in conjunction with the ImageIndex property to determine the file name  of an image that the mouse pointer is currently positioned over.

Data Type

String

See Also

Image Property, ImageCount Property, ImageIndex Property, ImageTitle Property


Web ImageIndex Property
ImageIndex Property

Description

Return the index number of the image the mouse pointer is positioned over

Visual Basic

[form.]control.ImageIndex

Remarks

The ImageIndex read-only property returns a number which identifies the image which the user has the mouse pointer positioned over. If the pointer is not positioned over an image, a value of 0 is returned. This number can be used as an index into the Image property array to determine the URL of the image.

Note  If the mouse pointer is not positioned over an image in the document, and the document has a background image, then a value of 1 will be returned. A background image is always the first image in the image list.

Data Type

Integer

See Also

Image Property, ImageCount Property, ImageFile Property, ImageTitle Property


Web ImageTitle Property
ImageTitle Property

Description

Return the title for the specified image

Visual Basic

[form.]control.ImageTitle(index)

Remarks

The ImageTitle property returns the title for the image specified by the index argument. The index may be a value in the range of 1 through the number of images in the document. An index value of 0 always returns an empty string.

This property array may be used in conjunction with the ImageIndex property to determine the title  of an image that the mouse pointer is currently positioned over.

Data Type

String

See Also

Image Property, ImageCount Property, ImageFile Property, ImageIndex Property


Web FontScale Property
FontScale Property

Description

Set or return the point size of fonts displayed by the control

Visual Basic

[form.]control.FontScale(index) [ = points ]

Remarks

Font sizes in HTML documents are expressed as integer values between 1 (the smallest size) and 7 (the largest size), with the default size being 3. Each of these font sizes are scaled to a Windows font point size by the control:

Font Size	Font Points	Description
1	9
2	10	Header 6 <H6>
3	11	Header 5 <H5>, Default
4	14	Header 4 <H4>
5	18	Header 3 <H3>
6	24	Header 2 <H2>
7	32	Header 1 <H1>
Therefore, a size 3 font corresponds to an 11-point Windows font, while an <H2> tag in the document corresponds to a 24-point font.

By setting the FontScale property, the application can change the point size of the fonts used in the document. The index value should be set to the logical font size that you wish to change (a value between 1 and 7), and the value assigned to the property should specify the point size to be used. The minimum point size is 6, and the maximum point size is 72. Setting the property value to zero causes the control to use the default point size for the given font size.

Data Type

Integer

See Also

FontFixed Property, FontHeading Property, FontNormal Property


Web Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	*LineUp	*LoadPrevious	*Reload	*Unload
DoClick	*Load	*PageDown	*Reset
*LineDown	*LoadNext	*PageUp	*Search
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


Web Load Method
Load Method

Description

Load and display the specified resource

Visual Basic

[form.]control.Load resource$

Remarks

The Load method loads the specified resource. The resource name may be a complete URL, or a base file name. The Resource property is updated to reflect the complete URL.

The resource argument specifies the URL or base file name of the resource to load.

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Web LoadNext Method
LoadNext Method

Description

Load the next document in the history list

Visual Basic

[form.]control.LoadNext

Remarks

The LoadNext method causes the next document in the control's history list to be loaded.

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, LoadPrevious Method


Web LoadPrevious Method
LoadPrevious Method

Description

Load the previous document in the history list

Visual Basic

[form.]control.LoadPrevious

Remarks

The LoadPrevious method causes the previous document in the control's history list to be loaded.

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, LoadNext Method


Web Unload Method
Unload Method

Description

Unload the current resource

Visual Basic

[form.]control.Unload

Remarks

The Unload method causes the current resource to be unloaded, clearing the control's window.

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Web Reload Method
Reload Method

Description

Reload the current document

Visual Basic

[form.]control.Reload

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Web Search Method
Search Method

Description

Submit a search keyword to an index document

Visual Basic

[form.]control.Search keyword$

Remarks

The Search method submits a keyword to a searchable document. This method is only supported for those documents that include the ISINDEX markup tag.

The keyword argument specifies the string to submit to the server.

Return Value

A value of zero is returned if the method completed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


Web LineUp Method
LineDown, LineUp Method

Description

Scroll the current document up or down one line

Visual Basic

[form.]control.LineDown
[form.]control.LineUp

Remarks

The LineUp method causes the current document view to scroll up one line, while the LineDown causes it to scroll down one line. These methods have no effect if the client window contains the entire document.

Note  To scroll to an absolute position the PostMessage API call should be used to send WM_VSCROLL messages to the control.

Return Value

None

See Also

Action Property, PageDown Method, PageUp Method


Web PageUp Method
PageDown, PageUp Method

Description

Scroll the current document up or down one page

Visual Basic

[form.]control.PageDown
[form.]control.PageUp

Remarks

The PageUp method causes the current document view to scroll up one page, while the PageDown causes it to scroll down one page. These methods have no effect if the client window contains the entire document.

Note  To scroll to an absolute position the PostMessage API call should be used to send WM_VSCROLL messages to the control.

Return Value

None

See Also

Action Property, LineDown Method, LineUp Method


Web Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Cancel	DragOver	KeyUp	*Paint
*Change	*Execute	*LastError	*Preview
Click	*FormReset	*Load	*Progress
*Connect	*FormSubmit	LostFocus	*QueryLoad
DblClick	GotFocus	MouseDown	*Redirect
*Disconnect	KeyDown	MouseMove	*Resize
DragDrop	KeyPress	MouseUp


Web Cancel Event
Cancel Event

Description

The Cancel event is generated when the current action has been cancelled

Visual Basic

Sub control_Cancel ( [Index As Integer] )

Remarks

This event is generated when the loading of a resource has been aborted by setting the Action property to the value WEB_ACTION_CANCEL.

See Also

Action Property


Web Execute Event
Execute Event

Description

The Execute event is generated when file contents must be viewed by an external program.

Visual Basic

Sub control_Execute ([Index As Integer,] Program As String, FileName As String)

Remarks

The Execute event is generated when a referenced file cannot be viewed by the browser control. The control attempts to match the file type, based on  it's extension, to a program on the local system that can be used to view the file.

The Program argument specifies the name of an executable program that can be used to display the file. The program name can only be determine if the file name extension has been registered.

The FileName argument is a string that specifies the local file name that contains the resource. If a remote file was referenced, this will be the name of a temporary cache file created by the control.

See Also

Preview Event, QueryLoad Event


Web FormReset Event
FormReset Event

Description

The FormReset event is generated before resetting the contents of the current form

Visual Basic

Sub control_FormReset ([Index As Integer,] Resource As String, Cancel As Integer)

Remarks

This event is generated when the user presses the reset button on the current form.

The Resource argument specifies the URL of the script that will receive the data. This can be used to determine if multiple forms are present in the document.

The Cancel argument is an integer flag that, when set to a non-zero value, cancels the resetting of the current form's controls.

See Also

FormSubmit Event


Web FormSubmit Event
FormSubmit Event

Description

The FormSubmit event is generated before the contents of the current form are submitted to the remote host.

Visual Basic

Sub control_FormSubmit ([Index As Integer,] Resource As String, FormData As String, Method As Integer, Cancel As Integer)

Remarks

This event is generated before the contents of the current form are submitted to the remote host for processing.

The Resource argument specifies the URL of the remote CGI script that receives the form data. This can be used to determine which form is being used, if multiple forms are contained within the document.

The FormData argument contains the actual URL-encoded data that will be transmitted to the remote host. Modifying this string will change the data submitted to the server.

The Method argument is an integer which specifies how the data is being submitted to the server. If set to a value of 1, the data is being sent via the GET method. A value of 2 indicates the data is being sent via the POST method.

The Cancel argument is an integer flag that, when set to a non-zero value, cancels the submission of the data to the remote server.

See Also

FormReset Event


Web Load Event
Load Event

Description

The Load event is generated after a resource has been loaded

Visual Basic

Sub control_Load ([Index As Integer,] Resource As String, ContentType As Integer)

Remarks

This event is generated when a resource has been loaded by the control.

The Resource argument specifies the URL of the resource that has been loaded.

The ContentType argument is an integer which specifies the type of resource that has been loaded. There are four basic resource types:

Value	Constant	Description
1	CONTENT_HTML	The resource is an HTML document
2	CONTENT_TEXT	The resource is a text file, and will be displayed using a fixed-width Courier font
3	CONTENT_IMAGE	The resource is an in-line graphics image referenced by the current document
4	CONTENT_SOUND	The resource is an audio file referenced by the current document
See Also

Preview Event, QueryLoad Event


Web Preview Event
Preview Event

Description

The Preview event allows a resource to be previewed before it is loaded

Visual Basic

Sub control_Preview ([Index As Integer,] FileName As String, ContentType As Integer, Cancel As Integer)

Remarks

This event is generated after the contents of a file have been retrieved (if the file is remote), but before the file is loaded by the viewer. This provides an opportunity for the application to open and read through (and potentially change) the contents of the file before it is viewed.

The FileName argument specifies the name of the local file that contains the data to be loaded by the control. If the data was transferred from a remote system, the name of the local cache file is passed to this event.

The ContentType argument is an integer which specifies the type of resource that will be loaded. There are four basic resource types.

Value	Constant	Description
1	CONTENT_HTML	The resource is an HTML document
2	CONTENT_TEXT	The resource is a text file, and will be displayed using a fixed-width Courier font
3	CONTENT_IMAGE	The resource is an in-line graphics image referenced by the current document
4	CONTENT_SOUND	The resource is an audio file referenced by the current document
The Cancel argument is an integer flag that, when set to a non-zero value, cancels the loading of the specified file.

See Also

Load Event, QueryLoad Event


Web Progress Event
Progress Event

Description

The Progress event is generated during data transfer

Visual Basic

Sub control_Progress ([Index As Integer,] ContentRead As Long, ContentLength As Long, Percent As Integer)

Remarks

This event is generated during the transfer of data from a remote host, indicating the amount of data received. For transfers of large amounts of data, this event can be used to update a progress bar or other user-interface control to provide the user with some visual feedback.

The ContentRead argument specifies the number of bytes that have been transferred from the remote host.

The ContentLength argument specifies the size of the remote resource in bytes. If this information is not provided by the remote server, this value will be zero.

The Percent argument is an integer with a value between 0 and 100 which specifies the percentage of data that's been read. If the remote server does not specify the size of the resource, this value will be zero.

See Also

Preview Event


Web QueryLoad Event
QueryLoad Event

Description

The QueryLoad event is generated before a resource has been loaded

Visual Basic

Sub control_QueryLoad ([Index As Integer,] Resource As String, Cancel As Integer)

Remarks

This event is generated before the resource is loaded, and provides an opportunity to change the URL or cancel the load.

The Resource argument specifies the URL of the resource that has been loaded. If this string is changed, that resource is loaded in place of the one originally specified.

The Cancel argument is an integer flag that, when set to a non-zero value, cancels the loading of the specified resource.

See Also

Load Event, Preview Event


Web Redirect Event
Redirect Event

Description

The Redirect event is generated when a remote resource has been moved

Visual Basic

Sub control_Redirect ([Index As Integer,] NewResource As String, Cancel As Integer)

Remarks

This event is generated when a remote server indicates that the requested resource has been relocated. This event is only generated if the AutoRedirect property is True.

The NewResource argument specifies the new URL of the resource that has been requested. If this string is changed, that resource is loaded in place of the one originally specified.

The Cancel argument is an integer flag that, when set to a non-zero value, cancels the redirection of the specified resource.

See Also

AutoRedirect Property


Web Control Errors
  Value                   Description

    22401                   Invalid handle to client
    22402                   Invalid paramter passed to function
    22403                   Unable to initialize library
    22404                   Unable to allocate memory
    22405                   Unable to resolve hostname
    22406                   Unable to create socket
    22407                   Unable to connect to remote host
    22408                   Unable to select socket
    22409                   Timeout reading socket
    22410                   Invalid HTTP server response
    22411                   Cannot open local file
    22412                   Cannot open local file
    22413                   Unable to read socket
    22414                   Unable to write socket
    22415                   End of data on socket
    22416                   Server is busy, try again later
    22417                   Operation has been canceled
    22418                   Resource has been moved
    22419                   Resource has not been modified
    22420                   Bad request to server
    22421                   Unauthorized request to server
    22422                   Payment required for resource
    22423                   Access to resource forbidden
    22424                   Resource not found on server
    22425                   Invalid method for this resource
    22426                   Resource not acceptable to client
    22427                   Proxy authentication required
    22428                   Resource is permanently removed
    22429                   Internal server error
    22430                   Method not supported by server
    22431                   Invalid response from gateway
    22432                   Server is unavailable
    22433                   Server gateway timeout
    22434                   Unexpected error returned from server


SocketWrench Control
  Windows Sockets Control
Properties    Methods     Events      Errors      License Agreement      Release Notes

Description

The SocketWrench/VB control uses the standard Windows Sockets library to provide network communication services for Visual Basic applications. The control supports both stream and datagram protocols, a buffered text mode for ease of use, and both client and server functionality in the same control.

File Name

CSWSKCTL.VBX, CSWSK16.OCX, CSWSK32.OCX

Object Type

Socket

Remarks

The SocketWrench/VB custom control provides network communication services for your Visual Basic application using a third-party TCP/IP protocol stack and compatible Windows Sockets library. The control offers the following features:

• Client and server functionality in a single control
• Support for blocking and non-blocking socket operations
• Convenient text mode for receiving data a line at a time
• Support for both stream and datagram protocols
• Send and receive urgent (out-of-band) data

Instead of using API calls, virtually all socket functions can be performed by setting control properties and responding to events. For those developers who are not familiar with the details of socket programming, SocketWrench can also insulate them from many of the common pitfalls, without sacrificing functionality or flexibility.

Each control that you use corresponds to one socket (which may or may not be connected to a remote host). If you need access to multiple sockets, you must use multiple controls, typically as a control array. This is most commonly needed when your application acts a server and must be able to handle several connections at one time.

Requirements

The sockets control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP product that supports the Windows Sockets 1.1 specification. The OLE controls require Visual Basic 4.0 or another compatible container. The Windows Sockets library must be located in the Windows directory or in a directory that is in the search path.

Distribution

When you distribute your application that uses the socket control, you should install the appropriate file in the Windows system directory. Note that it is not required that the end-user of your application use the same TCP/IP product that you’ve used for development.

Copyright

Copyright © 1995-1996, Catalyst Development Corporation. All rights reserved.


SocketWrench License
SocketWrench License Agreement

GRANT OF LICENSE.  CATALYST (Catalyst Development Corporation) grants to you, the end user, the right to use the Catalyst SocketWrench developers toolkit. (Known as the "SOFTWARE".) The SOFTWARE may be distributed to others, provided that the SOFTWARE is redistributed in it's original unmodified form, complete with all files, and no fee is charged for such distribution except for reasonable media and shipping charges..

DISTRIBUTION.  The user has a royalty-free right to reproduce and distribute executable files that incorporate the SOFTWARE. This right includes the distribution of the runtime module of the SOFTWARE, provided that the user: (a) distributes the runtime module only in conjunction with and as part of a software product; (b) includes a valid copyright notice on the software product; and (c) agrees to indemnify, hold harmless and defend the copyright holder against any claims or lawsuits, including attorney's fees, that arise from the use or distribution of your software product. The "runtime module" refers to the custom control library required during execution of your software product.

COPYRIGHT.  The SOFTWARE is owned by CATALYST and is protected by copyright laws and international treaty provisions. Therefore you must treat the SOFTWARE like any other copyrighted material (e.g. a book or musical recording), except that you may copy and redistribute the SOFTWARE in accordance with this license.

OTHER RESTRICTIONS.  You may not RENT or LEASE the SOFTWARE. You may not reverse engineer, decompile or disassemble the SOFTWARE, except to the extent such restriction is expressly prohibited by law. Except as described above, you may not legally copy or distribute the SOFTWARE (which includes the documentation, object code and supporting programs), in whole or in part. All rights not specifically granted are reserved by the copyright holder.

NO WARRANTY. The SOFTWARE is provided "AS-IS", without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the performance of the programs is with the user. CATALYST does not warrant that the operation of the programs will be uninterrupted or error-free. CATALYST assumes no responsibility or liability of any kind for errors in the programs or documentation, or for the consequences of any such errors. Should the the SOFTWARE prove defective, you assume the cost of all necessary servicing, repair or correction. Some states do not allow limitations on implied warranties, so the above limitations may not apply to you.

NO LIABILITY FOR CONSEQUENTIAL DAMAGES.  In no event shall CATALYST or its suppliers be liable for any damages whatsoever (including, with limitation, damages for loss of business profits, business interruption, or other pecuniary loss) arising out of the use or inability of this CATALYST product, even if CATALYST has been advised of such damages. This agreement is governed by the laws of the state of California.


TCP Control Properties
Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Accept	*HostAddress	*Linger	*RecvLen	Top
*Action	*HostFile	*Listening	*RecvNext	*Urgent
*AddressFamily	*HostName	*LocalAddress	*RemotePort	*Vendor
*AtMark	Index	*LocalName	*RemoteService	*Version
*AutoResolve	*InLine	*LocalPort	*ReuseAddress
*Backlog	*Interval	*LocalService	*Route
*Binary	*IsBlocked	*MaxDatagram	*SendData
*Blocking	*IsClosed	*MaxSockets	*SendLen
*Broadcast	*IsReadable	Name	*Shutdown
*BufferSize	*IsWritable	*Peek	*SocketType
*Connected	*KeepAlive	*PeerAddress	*State
*GetFirstHost	Left	*PeerName	TabIndex
*GetNextHost	*LastError	*PortString	Tag
*Handle	*Library	*Protocol	*Timeout


TCP Accept Property
Accept Property

Description

A write-only property, that when set to the value of a listening socket’s handle, accepts the connection. The listening socket is not closed and may continue to listen for new client connections.

Visual Basic

[form.]Socket.Accept = handle%

Remarks

Setting this property to a socket that is not listening for connections will generate an error. If the Accept property is set to the value of the current socket’s handle, the effect is the same as if the SOCKET_ACCEPT action has been taken.

Data Type

Integer

See Also

Action Property, Backlog Property, Listening Property, Accept Event


TCP Action Property
Action Property

Description

Setting this property causes the socket to take some action, such as creating a socket, connecting to a remote system or closing a connection.

Visual Basic

[form.]Socket.Action = action%

Remarks

The following table lists the actions that a socket control may take:

Value	Constant	Description
1	SOCKET_OPEN	Create a socket using the AddressFamily, Protocol and Type properties. This action is commonly used to create datagram sockets, or if supported by the TCP vendor, raw sockets.
2	SOCKET_CONNECT	Connect to a remote system specified by the HostAddress or HostName properties. If a socket has not already been created, this action will create it.
3	SOCKET_LISTEN	Listen on a socket for incoming connections on the port specified by the LocalPort or LocalService properties. If a socket has not already been created, this action will create it.
4	SOCKET_ACCEPT	Accept an incoming connection on the socket. The listening socket connection is closed and the client is connected. To resume listening for new connections, the Action must be set to SOCKET_LISTEN again. This approach allows only one incoming connection per listening  socket
5	SOCKET_CANCEL	Cancel the current blocking operation. This action only has meaning for blocking sockets.
6	SOCKET_FLUSH	Flush the contents of the send and receive socket buffers.
7	SOCKET_CLOSE	Close the socket, and if connected, break the connection with the remote system. This action should be taken before the control is unloaded from the form.
8	SOCKET_ABORT	Immediately close the socket without waiting for remaining data to be written out. This action should only be taken under extreme circumstances.
9	SOCKET_STARTUP	Explicitly load and initialize the Windows Sockets library. Typically this action is not required because this is done automatically when any control function is taken which requires network access (such as attempting a connection to a remote host).
10	SOCKET_CLEANUP	Explicitly unload the Windows Sockets library. Typically this action is not required because this is done when the control is unloaded.
Note   The Action property is included for compatibility with Visual Basic 3.0 and earlier versions. For additional functionality, development environments which support OLE controls should use the new methods listed in the Methods table.

Data Type

Integer

See Also

Blocking Property, Connected Property, Library Property, Listening Property, MaxSockets Property,State Property, Timeout Property


TCP AddressFamily Property
AddressFamily Property

Description

Sets or returns the address family for the socket.

Visual Basic

[form.]Socket.AddressFamily [= aftype%]

Remarks

The address family value should be set to the constant AF_INET. This property is included only for completeness and future expansion.

Data Type

Integer

See Also

Protocol Property, SocketType Property


TCP AtMark Property
AtMark Property

Description

A read-only property that returns True if the next receive will return urgent data.

Visual Basic

[form.]Socket.AtMark

Remarks

This property can only be used if the socket type is SOCK_STREAM and the InLine property has been set to True. Reading this property is the same as using the SIOCATMARK option with the ioctlsocket function.

Data Type

Integer (Boolean)

See Also

RecvData Property, Urgent Property, Read Event


TCP Backlog Property
Backlog Property

Description

Sets or returns the number of connections that may be accepted by a listening socket.

Visual Basic

[form.]Socket.Backlog [= backlog%]

Remarks

This property must be set to the desired value before the SOCKET_LISTEN action is taken. If the value is less than one or greater than five, it’s value is silently changed to nearest legal value.

Data Type

Integer

See Also

Accept Property, Listening Property, Accept Event


TCP Binary Property
Binary Property

Description

Sets or returns the binary mode flag for the current socket. If set to a value of False, then subsequent reads on the socket return lines of text terminated by newlines.

Visual Basic

[form.]Socket.Binary [= { True | False }]

Remarks

This property may only be set for buffered sockets of type SOCK_STREAM, and may not be changed after a connection has been established with a remote system.

Data Type

Integer (Boolean)

See Also

BufferSize Property, RecvData Property


TCP Broadcast Property
Broadcast Property

Description

Determines if datagrams should be broadcast over the network

Visual Basic

[form.]Socket.Broadcast [= { True | False }]

Remarks

If set to a value of True, the datagram written to the socket will be broadcast to all systems on the network. Use of this property is restricted to SOCK_DGRAM socket types.

Data Type

Integer (Boolean)

See Also

InLine Property, KeepAlive Property, ReuseAddress Property, Route Property


TCP BufferSize Property
BufferSize Property

Description

Set the send and receive buffer sizes for the socket

Visual Basic

[form.]Socket.BufferSize [= bufsize%]

Remarks

This property sets the size of the send and receive buffers for SOCK_STREAM socket types. A buffer size of 0 indicates that no buffering should be done. Buffering reads and writes on the socket is recommended if the socket is non-blocking, and required if the Binary property has been set to a value of False.

Data Type

Integer

See Also

Binary Property, RecvData Property, Read Event


TCP GetFirstHost Property
GetFirstHost Property

Description

Return the name of the first host in the host table

Visual Basic

[form.]Socket.GetFirstHost

Remarks

Reading this property returns the name of the first host in the specified host file. If there is no host file, or the file is empty, this property will return an empty string.

Data Type

String

See Also

GetNextHost Property, HostFile Property


TCP GetNextHost Property
GetNextHost Property

Description

Return the name of the next host in the host table

Visual Basic

[form.]Socket.GetNextHost

Remarks

Reading this property returns the name of the next host in the specified host file. If the last host entry has been read, this property will return an empty string.

Data Type

String

See Also

GetFirstHost Property, HostFile Property


TCP HostFile Property
HostFile Property

Description

Sets or returns the name of the host file

Visual Basic

[form.]Socket.HostFile [= hostfile$]

Remarks

This property should be set to the name of the host file used by the Windows Sockets library. If no directory is provided as part of the file name, the directories listed in the PATH environment variable are searched. If the host file is located, each host entry is read into memory and returned by the GetFirstHost and GetNextHost properties.

Note that the host file must be a standard UNIX-style text file. Blank lines, or any characters that follow a hash-mark (#) are ignored.

Data Type

String

See Also

GetFirstHost Property, GetNextHost Property


TCP InLine Property
InLine Property

Description

Sets or returns if urgent data is received in-line with non-urgent data

Visual Basic

[form.]Sockett.InLine [= { True | False }]

Remarks

This property controls how urgent (out-of-band) data is handled when reading data from the socket. If set to a value of True, urgent data is placed in the data stream along with non-urgent data. To determine if the data that is being read is urgent, the AtMark property can be read.

Note  Urgent data is sent and received directly from the socket, and is not buffered even if buffering is enabled. It is recommended that you do not enable buffering if urgent data is being received in-line.

Data Type

Integer (Boolean)

See Also

Urgent Property, Read Event


TCP Interval Property
Interval Property

Description

Set or return the number of milliseconds between calls to the control's Timer event

Visual Basic

[form.]Socket.Interval [= milliseconds]

Remarks

This property specifies the number of milliseconds between calls to the Timer event. A value of zero indicates that the timer is disabled and no events will be generated. The maximum interval value is 65536 milliseconds, which is slightly more than one minute.

There are a limited number of timers available (16 in the Windows environment). Setting the interval to a non-zero value when no timers are available will generate a runtime error.

Data Type

Long

See Also

Timer Event


TCP KeepAlive Property
KeepAlive Property

Description

Set or return if "keep alives" are sent on a connected socket

Visual Basic

[form.]Socket.KeepAlive [= { True | False }]

Remarks

Setting this property to a value of True indicates that packets are to be sent to the remote system when no data is being exchanged to keep the connection active. This property can only be set for SOCK_STREAM socket types.

Data Type

Integer (Boolean)

See Also

Broadcast Property, InLine Property, ReuseAddress Property, Route Property


TCP Linger Property
Linger Property

Description

Set or return the number of seconds to linger on a close

Visual Basic

[form.]Socket.Linger [= nsecs%]

Remarks

Setting this property to a value greater than zero indicates that the SOCKET_CLOSE action should wait up to the specified number of seconds for any data on the socket to be written before it is closed. A value of zero indicates that the socket should be closed immediately (but gracefully, without data loss).

Data Type

Integer

See Also

Disconnect Event


TCP Listening Property
Listening Property

Description

Returns if the socket is listening for connections

Visual Basic

[form.]Socket.Listening

Remarks

This read-only property returns True if the socket is listening for connections after the SOCKET_LISTEN action is taken.

Data Type

Integer (Boolean)

See Also

Accept Property, Backlog Property, Accept Event


TCP LocalPort Property
LocalPort Property

Description

Set or return the port number for a local listening socket

Visual Basic

[form.]Socket.LocalPort [= portno%]

Remarks

This property is used to set the port number that a local server will listen on for connections. If the port number specifies a well-known port, the LocalService property will be updated with that name.

Data Type

Integer

See Also

LocalService Property, RemotePort Property


TCP LocalService Property
LocalService Property

Description

Set or return the name of a well-known local port

Visual Basic

[form.]Socket.LocalService [= servicename$]

Remarks

This property is used to set the port that a local server will listen on for connections. If the service name does not exist, an error is generated. The LocalPort property is updated to reflect the service’s port number.

Data Type

String

See Also

LocalPort Property, RemoteService Property


TCP Peek Property
Peek Property

Description

Set or return if data is to be removed from the socket when read

Visual Basic

[form.]Socket.Peek [= { True | False }]

Remarks

If this property is set to a value of  True, the data that is read from the socket is not removed, and may be read again.

Note  This property is automatically reset to a value of  False after data has been read from the socket.

Data Type

Integer (Boolean)

See Also

RecvData Property, Read Event


TCP PeerAddress Property
PeerAddress Property

Description

Return the IP address of the remote peer

Visual Basic

[form.]Socket.PeerAddress

Remarks

This read-only property returns the IP address of a the peer in dot notation (four numbers separated by periods). The peer is the remote system that is either connected to, or was last sent data (if a connectionless socket is being used).

Data Type

String

See Also

HostAddress Property, LocalAddress Property, PeerName Property


TCP PeerName Property
PeerName Property

Description

Return the name of the remote peer

Visual Basic

[form.]Socket.PeerName

Remarks

This read-only property returns the name of the peer. The peer is the remote system that is either connected to, or was last sent data (if a connectionless socket is being used).

Data Type

String

See Also

HostName Property, LocalName Property, PeerAddress Property


TCP PortString Property
PortString Property

Description

Return the local host IP address and port number

Visual Basic

[form.]Socket.PortString

Remarks

This property returns the local host IP address and port number as comma-delimited string. The first four numbers specifies the address, and the last two numbers are the low and high bytes of the local port number. This string is the same that is used with the PORT command in the File Transfer Protocol (FTP).

Data Type

String


TCP Protocol Property
Protocol Property

Description

Set or return the protocol that should be used to create the socket

Visual Basic

[form.]Socket.Protocol [= proto%]

Remarks

This property may only be set before a socket has been created, or after it has been closed. Supported socket protocols are:

Value	Constant	Description
0	IPPROTO_IP	Default IP protocol. This value indicates that the protocol appropriate for the socket type should be used, and is the default.
6	IPPROTO_TCP	Transmission Control Protocol. This protocol should be used with stream sockets.
17	IPPROTO_UDP	User Datagram Protocol. This protocol should be used with datagram sockets
There may be other protocols supported by your vendor, or in future versions of the Windows Sockets specification. Consult your TCP/IP documentation to determine what protocols are valid.

Data Type

Integer

See Also

AddressFamily Property, SocketType Property


TCP ReuseAddress Property
ReuseAddress Property

Description

Set or return if an address can be reused

Visual Basic

[form.]Socket.ReuseAddress [= { True | False }]

Remarks

Setting this property to a value of True allows the address that the socket is listening on to be reused. By default this property is False.

Data Type

Integer (Boolean)

See Also

Broadcast Property, InLine Property, KeepAlive Property, Route Property


TCP Route Property
Route Property

Description

Set or return if packets should be routed

Visual Basic

[form.]Socket.Route [= { True | False }]

Remarks

Setting this property to False tells the socket library that packets are not to be routed, but rather sent directly to the network interface.

Data Type

Integer (Boolean)

See Also

Broadcast Property, InLine Property, KeepAlive Property, ReuseAddress Property


TCP Shutdown Property
Shutdown Property

Description

Stop reading and/or writing on the socket

Visual Basic

[form.]Socket.Shutdown [= what%]

Remarks

This write-only property shuts down reading and/or writing on the socket. Any further attempt to send or receive data will return an error on the socket. The possible values that may be assigned to this property are:

Value	Constant	Description
0	SOCKET_READ	All subsequent attempts to read data from the socket are disallowed. If the socket is buffered, it is possible that data may still be read until the buffer is exhausted.
1	SOCKET_WRITE	All subsequent attempts to write data to the socket are disallowed. If the socket is buffered, it is possible that data may be written until the buffer is full.
2	SOCKET_READWRITE	Both reads and writes to the socket are disallowed.
Note that shutting down a socket is not the same as closing it. The socket will remain connected, and no resources will be freed until the SOCKET_CLOSE action is taken.

Data Type

Integer

See Also

IsReadable Property, IsWritable Property


TCP SocketType Property
SocketType Property

Description

Sets or returns the type of socket that should be created

Visual Basic

[form.]Socket.SocketType [= socktype%]

Remarks

This property may only be set before a socket has been created, or after it has been closed. Supported socket types are:

Value	Constant	Description
1	SOCK_STREAM	Stream socket used with the TCP protocol. This type of socket provides a reliable byte stream that may be read similar to the way a file is read.
2	SOCK_DGRAM	Datagram socket used with the UDP protocol. This type of socket is used to transfer datagrams using a fast (but unreliable) protocol. Datagrams may arrive out of sequence, or not at all. Retransmission of lost datagrams is the responsibility of the application.
3	SOCK_RAW	A raw socket that is commonly used to send ICMP messages over the network. This socket type may or may not be supported by your TCP/IP vendor.
There may be other types of sockets supported by your vendor, or in future versions of the Windows Sockets specification. Consult your TCP/IP documentation to determine what socket types are valid.

Data Type

Integer

See Also

AddressFamily Property, Protocol Property


TCP State Property
State Property

Description

Return the current state of the socket

Visual Basic

[form.]Socket.State

Remarks

This read-only property returns the state of the socket. This property should be checked on blocking sockets to determine if the socket is in use before taking some action. The possible values returned by this property are:

Value	Constant	Description
0	SOCKET_UNUSED	The socket has not been created. Attempts to use the socket will generate an error.
1	SOCKET_IDLE	The socket exists, but is not currently in use. A blocking socket operation can be executed at this point.
2	SOCKET_LISTENING	The socket is listening for connections from remote hosts
3	SOCKET_CONNECTING	The socket is in the process of connecting to a remote host
4	SOCKET_ACCEPTING	The socket is in the process of accepting a connection from a remote client
5	SOCKET_RECEIVING	The socket is in the process of receiving data
6	SOCKET_SENDING	The socket is in the process of sending data
7	SOCKET_CLOSING	The socket is being closed. Subsequent attempts to access the socket will result in an error.
Note that for non-blocking sockets, the only possible states that may be returned are SOCKET_UNUSED, SOCKET_IDLE or SOCKET_CLOSING.

Data Type

Integer

See Also

IsBlocked Property, Blocking Event, Cancel Event, Timeout Event


TCP Timeout Property
Timeout Property

Description

Set or return the amount of time until a blocking operation fails

Visual Basic

[form.]control.Timeout [= msecs ]

Remarks

Setting this property specifies the number of milliseconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely.

Data Type

Long

See Also

RecvData Property, SendData Property


TCP Urgent Property
Urgent Property

Description

Send or receive urgent data

Visual Basic

[form.]Socket.Urgent [= { True | False }]

Remarks

This Boolean property affects how the RecvData and SendData properties read or write data to the socket. If set to a value of True, urgent (out-of-band) data will be read or written. All reads or writes of urgent data are unbuffered. The property value will automatically be reset to a value of False after the socket has been read or written.

Note  Not all implementations may support more than one byte of urgent data if the data is not being received in-line. Refer to the InLine property for additional information.

Data Type

Integer (Boolean)

See Also

InLine Property, RecvData Property, SendData Property, Read Event


TCP MaxDatagram Property
MaxDatagram Property

Description

Return the maximum size of a UDP datagram

Visual Basic

[form.]Socket.MaxDatagram

Remarks

The MaxDatagram property returns the maximum number of bytes that may be transmitted in a single write operation on a SOCK_DGRAM type socket. Attempting to send more than this number of bytes will result in an error, with no data being written.

Data Type

Long

See Also

MaxSockets Property, SendData Property, SocketType Property


TCP MaxSockets Property
MaxSockets Property

Description

Return the maximum number of sockets that can be created

Visual Basic

[form.]Socket.MaxSockets

Remarks

The MaxSockets property returns the maximum number of sockets that may be created, system wide. This value is determined by the underlying TCP/IP stack.

Data Type

Integer

See Also

MaxDatagram Property


TCP Control Methods
Methods

All of the methods for this control are listed in the following table. Methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Abort	*Connect	*Listen	*Startup
*Cancel	*Disconnect	*Open	*Write
*Cleanup	*Flush	*Read
Note Custom methods are only supported by the 16-bit and 32-bit OLE controls in Visual Basic 4.0 or later.


TCP Abort Method
Abort Method

Description

Terminate the connection with a remote server

Visual Basic

[form.]control.Abort

Remarks

The Abort method immediately closes the socket, without waiting for any remaining data to be written out. This method should only be used when the connection must be closed immediately before the application terminates.

Return Value

A value of zero is returned if the connection was terminated successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Connect Method, Disconnect Method


TCP Cleanup Method
Cleanup Method

Description

Unload the Windows Sockets library

Visual Basic

[form.]control.Cleanup

Remarks

The Cleanup method terminates any connection established by the control and unloads the Windows Sockets library. This method is not typically used since this is done automatically when the control is unloaded.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, Startup Method


TCP Flush Method
Flush Method

Description

Flush the contents of the send and receive socket buffers.

Visual Basic

[form.]control.Flush

Return Value

A value of zero is returned if the control buffers were flushed successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


TCP Listen Method
Listen Method

Description

Listen for incoming connections

Visual Basic

[form.]control.Listen

Remarks

The Listen method causes the control to listen on a socket for incoming connections on the port specified by the LocalPort or LocalService properties. If a socket has not already been created, this action will create it.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property


TCP Open Method
Open Method

Description

Create a new socket

Visual Basic

[form.]control.Open

Remarks

Create a socket using the AddressFamily, Protocol and Type properties. This method is commonly used to create datagram sockets, or if supported by the TCP vendor, raw sockets.

Return Value

A value of zero is returned if a socket was created successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, MaxSockets Property


TCP Startup Method
Startup Method

Description

Initialize the Windows Sockets library

Visual Basic

[form.]control.Startup

Remarks

This method explicitly loads and initializes the Windows Sockets library. Typically this is not required because it's done automatically when any control function is taken which requires network access (such as attempting a connection to a remote host).

Return Value

A value of zero is returned if the library was initialized successfully. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

See Also

Action Property, MaxDatagram Property, MaxSockets Property, Cleanup Method


TCP Control Events
Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk.

*Accept	*Connect	*Read	*Write
*Blocking	*Disconnect	*Timeout
*Cancel	*LastError	*Timer


TCP Accept Event
Accept Event

Description

The Accept event is generated when a remote host connects to a listening socket.

Visual Basic

Sub Socket_Accept ([Index As Integer,]SocketID As Integer)

Remarks

This event is generated for sockets that are listening for connections from a remote host. A connection with the remote system is not actually established until it has been accepted by the listening server.

The SocketID argument specifies the socket descriptor of the listening socket. To accept the connection, one of the following actions must be taken:

•   The socket control sets the Action property to a value of SOCKET_ACCEPT. This allows the socket that was listening to connect with the remote host. However, this method closes the listening socket, so only one host can establish a connection with the application.

•   A second socket has it’s Accept property set to the value of SocketID. The second socket accepts the connection on behalf of the server, and the original socket may continue to listen for additional connections.

Once the connection has been established, the PeerAddress or PeerName properties may be used to determine the name of the remote host that has connected with the application.

See Also

Accept Property, Action Property, PeerAddress Property, PeerName Property


TCP Blocking Event
Blocking Event

Description

The Blocking event is generated whenever a blocking operation occurs

Visual Basic

Sub Socket_Blocking ([Index As Integer,]StatusAs Integer, Cancel As Integer)

Remarks

This event is generated immediately before a blocking operation takes place, and provides a kind of blocking hook function for the application.

The Status argument specifies which blocking action is about to be taken. For a list of values, refer to the State property.

The Cancel argument allows the blocking operation to be canceled if the value is set to True. The blocking function will fail with the error WSAEINTR.

Note  It is not recommended that code be placed in this event that would take any significant amount of time to complete or calls DoEvents to yield time to other tasks.

See Also

State Property, Cancel Event


TCP Cancel Event
Cancel Event

Description

The Cancel event is generated when a blocking operation is canceled

Visual Basic

Sub Socket_Cancel ([Index As Integer,]Status As Integer, Response As Integer)

Remarks

This event is generated when a blocking operation on the socket, such as sending or receiving data, is canceled with the SOCKET_CANCEL action.

The Status argument specifies which blocking operation was canceled. For a list of values, refer to the State property.

The Response argument determines if a WSAEINTR error is generated in response to the canceled operation. The possible values are:

Value	Constant	Description
0	SOCKET_ERRIGNORE	Ignore the canceled event and return as though the operation completed successfully.
1	SOCKET_ERRDISPLAY	Return the WSAEINTR error to the canceled socket operation. This is the default response to the event.
Setting Response to ignore the canceled event can result in unexpected errors. For example, if a blocking read on the socket is cancelled, the WSAEWOULDBLOCK error may be returned.

See Also

State Property, Blocking Event, Error Event


TCP Timeout Event
Timeout Event

Description

The Timeout event is fired when a blocking operation times out

Visual Basic

Sub Socket_Timeout ([Index As Integer,] Status As Integer, Response As Integer)

Remarks

This event is generated when a blocking socket operation, such as sending or receiving data, times out.

The Status argument specifies which blocking operation timed out. For a list of values, refer to the State property.

The Response argument determines if a WSAETIMEDOUT error is generated. The possible values are:

Value	Constant	Description
0	SOCKET_ERRIGNORE	Ignore the timeout and return as though the operation completed successfully
1	SOCKET_ERRDISPLAY	Return the WSAETIMEDOUT error to the timed-out socket operation. This is the default response to the event.
See Also

State Property, Timeout Property, Cancel Event


TCP Timer Event
Timer Event

Description

The Timer event is fired when the control's preset timer interval expires

Visual Basic

Sub Socket_Timer ( [Index As Integer] )

Remarks

This event is generated when the control's timer interval has elapsed. The frequency is specified in milliseconds by setting the Interval property.

See Also

Interval Property